|
| 1 | +## How to Contribute to the L5 Website |
| 2 | + |
| 3 | +Thanks for your interest in contributing to L5 documentation. |
| 4 | + |
| 5 | +Use this repository if you want to: |
| 6 | + |
| 7 | +* Improve reference pages |
| 8 | +* Write or edit tutorials |
| 9 | +* Add screenshots or examples |
| 10 | +* Improve wording, structure, or beginner explanations |
| 11 | + |
| 12 | +If you discover a bug or have an idea for a new feature on the website you'd like to add, please begin by submitting an issue so that we can discuss it. |
| 13 | + |
| 14 | +**For contributing to the L5 library** instead of the website, visit the [L5 code repository](https://github.com/L5lua/L5). |
| 15 | + |
| 16 | +## Working on the site locally |
| 17 | + |
| 18 | +The documentation site is built with [Material for mkdocs](https://squidfunk.github.io/mkdocs-material/). |
| 19 | + |
| 20 | +1. **Fork** this repo so that you have your own independent copy located at *github.com/YOUR-USERNAME/L5-website*. |
| 21 | +2. **Clone** your repository to your computer, with GitHub Desktop or in the command line: |
| 22 | +```bash |
| 23 | +git clone https://github.com/YOUR-USERNAME/L5-website.git |
| 24 | +cd L5-website |
| 25 | +``` |
| 26 | +3. Install dependencies |
| 27 | +```bash |
| 28 | +pip install mkdocs-material |
| 29 | +``` |
| 30 | +*If you are working on an OS with an externally-managed python environment, you may have additional steps. For example, in Debian/Ubuntu-based systems:* |
| 31 | +```sh |
| 32 | +sudo apt install pipx |
| 33 | +pipx ensurepath |
| 34 | +# then restart shell or source your config |
| 35 | +source ~/.bashrc # or your shell config |
| 36 | +pipx install mkdocs |
| 37 | +pipx inject mkdocs mkdocs-material |
| 38 | +``` |
| 39 | + |
| 40 | +*Or in Void Linux:* |
| 41 | +```sh |
| 42 | +sudo xbps-install -S python3-pipx |
| 43 | +pipx install mkdocs |
| 44 | +pipx inject mkdocs mkdocs-material |
| 45 | +``` |
| 46 | + |
| 47 | +4. Make your edits |
| 48 | +* Edit markdown files in the `docs/` folder |
| 49 | +* `mkdocs.yml` lists all pages in the nav |
| 50 | +5. Test locally |
| 51 | +```bash |
| 52 | +mkdocs serve |
| 53 | +``` |
| 54 | +Visit `http://localhost:8000` to preview changes. |
| 55 | +6. Commit and push to your fork |
| 56 | +```bash |
| 57 | +git add . |
| 58 | +git commit -m "Description of changes" |
| 59 | +git push origin main |
| 60 | +``` |
| 61 | +7. Create a pull request |
| 62 | +* On GitHub open a *Pull Request* from your fork to the main website repo |
| 63 | + |
| 64 | +You do **not** need special permission to fork, and you do **not** need to create a branch in the main repository. |
| 65 | + |
| 66 | +Most contributors work directly on the `main` branch of **their fork**. |
| 67 | + |
| 68 | +### Notes for Contributors |
| 69 | + |
| 70 | +* Don't commit the `site/` folder (it's auto-generated). |
| 71 | +* Only edit files in `docs/` (and `mkdocs.yml` if adding a main navigation page) |
| 72 | +* The live site is automatically built by GitHub Actions when Pull Requests are merged |
| 73 | + |
| 74 | +### Branches |
| 75 | + |
| 76 | +* [main](https://github.com/L5lua/L5-website/tree/main) is where the site is edited |
| 77 | +* [gh-pages](https://github.com/L5lua/L5-website/tree/gh-pages) is built automatically through a [workflow](https://github.com/L5lua/L5-website/blob/main/.github/workflows/deploy.yml) action from main. It serves the github pages site. |
| 78 | +* [gh-pages-lite](https://github.com/L5lua/L5-website/tree/gh-pages-lite) is a manually-built branch holding the offline version of the website, without images, for downloading through the [Offline Documentation](https://l5lua.org/download/#offline-documentation) section of the Download page. |
| 79 | + |
0 commit comments