mirror of
https://codeberg.org/Codeberg/Documentation.git
synced 2026-06-16 05:13:54 -07:00
131 lines
4.6 KiB
Markdown
131 lines
4.6 KiB
Markdown
# Codeberg Documentation
|
|
|
|
This repository contains the [documentation for Codeberg](https://docs.codeberg.org/), with some code to build it into
|
|
a static website.
|
|
|
|
Please have a look into it and consider to help writing the Documentation.
|
|
This is still very much work-in-progress, the more useful material we collect, the better we can later present it!
|
|
All contributions are very welcome!
|
|
|
|
For an introduction on contributing to Codeberg Documentation, please have a look
|
|
at [the section on improving the documentation](https://docs.codeberg.org/improving-documentation/).
|
|
|
|
## Usage
|
|
|
|
### Local Development using nodejs
|
|
|
|
If you want to work on the documentation, for example by writing your own articles,
|
|
the easiest way to do so is to fork the documentation repository and develop locally.
|
|
|
|
To learn how to get `pnpm` see the [PNpm website](https://pnpm.io).
|
|
|
|
First, run
|
|
|
|
`pnpm install`
|
|
|
|
to install all dependencies (they will be installed only for this project, not globally).
|
|
You only have to do this once.
|
|
|
|
Then run
|
|
|
|
`pnpm run dev`
|
|
|
|
to start a development web server that by default is listening at `http://localhost:8080`.
|
|
|
|
Now you can simply change, add or remove files, save them and the development server
|
|
should automatically reload all changed pages using the amazing Browsersync.
|
|
|
|
When you're done, commit your changes to your fork and write a pull request for
|
|
Codeberg/Documentation. We're happy about every contribution!
|
|
|
|
### Local development using the Dockerfile
|
|
|
|
If you do not have nodejs installed or do not want to run the development web server directly on your host,
|
|
you can also use a docker container.
|
|
|
|
You must have a container-engine installed (docker, podman, etc.)
|
|
|
|
First build the container image:
|
|
|
|
```shell
|
|
docker build --tag codeberg-docs:dev .
|
|
```
|
|
|
|
You do not have to rebuild the image every time. Once you build the image you can always start the development
|
|
webserver using the container engine:
|
|
|
|
```shell
|
|
docker run --name "codeberg-docs" --rm --tty --interactive --volume "${PWD}:/docs" --publish "127.0.0.1:8080:8080/tcp" codeberg-docs:dev
|
|
```
|
|
|
|
Use the "External" URL the container outputs on startup to access your documentation.
|
|
|
|
Changes to files in the documentation are reflected in the browser as the server regularly updates the generated files.
|
|
|
|
Use `Ctrl-C` to exit / end the container.
|
|
|
|
The parameters are:
|
|
|
|
`--rm` removes the container after it's use
|
|
`--volume` mounts the current (documentation repository root) folder to `/docs` in the container.
|
|
|
|
`codeberg-docs:dev` refers to the container image built in the first step (using `docker build`).
|
|
|
|
### Build & Deployment
|
|
|
|
Like for local development, before building and deploying you first have to install
|
|
the dependencies (once):
|
|
|
|
`pnpm install`
|
|
|
|
To build the entire website to the `_site` directory run
|
|
|
|
`pnpm run build`
|
|
|
|
Instead, to directly publish the page to Codeberg pages, you can also run
|
|
|
|
`pnpm run deploy`
|
|
|
|
which includes a call to `pnpm run build`.
|
|
|
|
### Check and fix formatting errors
|
|
|
|
Before you create a pull request with your changes, you should check and fix formatting errors.
|
|
Use the following command to fix formatting errors automatically:
|
|
|
|
`pnpx prettier . -w`
|
|
|
|
With the following command you can check if there are any formatting errors remaining:
|
|
|
|
`pnpx prettier . -c`
|
|
|
|
In addition you should also run the linter which is also used when checking pull requests:
|
|
|
|
`pnpx cspell lint --no-progress --gitignore '{**,.*}/{*,.*}'`
|
|
|
|
If this shows any errors, please fix them before committing your changes and creating a pull request.
|
|
|
|
### Technical Information
|
|
|
|
This website uses [Eleventy](https://www.11ty.dev/), a static site generator.
|
|
|
|
It's supplied as a dev-dependency in `package.json` and its dependencies are locked
|
|
with `package-lock.json` to try to ensure reproducible builds.
|
|
|
|
It also uses [PageFind](https://pagefind.app/), a static search library.
|
|
|
|
Deployment previews are generated for every PR using [Surge.sh](https://surge.sh/)
|
|
through the corresponding [Woodpecker plugin](https://woodpecker-ci.org/plugins/surge-preview).
|
|
|
|
A spellchecker is used to check for spelling errors in the documentation.
|
|
To add exceptions to the spellchecker, add them to the `.cspell.json` file.
|
|
|
|
This project is deployed to Codeberg via [a cron job](https://codeberg.org/Codeberg-Infrastructure/scripted-configuration/src/branch/main/hosts/static/home/build/build_docs.sh)
|
|
executed on the Codeberg infrastructure.
|
|
|
|
## License and Contributors
|
|
|
|
This website (excluding bundled fonts) is licensed under CC BY-SA 4.0. See the [LICENSE](LICENSE.md) file for details.
|
|
|
|
Please refer to the [commit log](https://codeberg.org/Codeberg/Documentation/commits/branch/main)
|
|
for an exhaustive list of contributors to Codeberg Documentation.
|