diff --git a/README.md b/README.md index 4ad5090c9..7cece2045 100644 --- a/README.md +++ b/README.md @@ -10,69 +10,69 @@ The Pi-hole[®](https://pi-hole.net/trademark-rules-and-brand-guidelines/) is a ## Documentation & User Guides -This repo is the source for the official [Pi-hole documentation](https://docs.pi-hole.net/). +This repository is the source for the official [Pi-hole documentation](https://docs.pi-hole.net/). -### How to contribute +### How to Contribute -To add a new link on the navigation panel you need to edit the `mkdocs.yml` file in the root of the repo. There is a guide for building the navbar [on the mkdocs wiki](https://www.mkdocs.org/user-guide/configuration/#nav) +**Adding a New Link to the Navigation Panel:** -To add a new document or guide. +- Edit the `mkdocs.yml` file at the root of the repository. +- Follow the guide for building the navbar on the [MkDocs Wiki](https://www.mkdocs.org/user-guide/configuration/#nav). -- Navigate to the directory where it will be hosted. - E.g. guides are in `docs/guides` -- Create the file using a URL friendly filename. - E.g. `docs/guides/url-friendly.md` -- Edit your document using Markdown, there are loads of resources available for the correct syntax. +**Adding a New Document or Guide:** -### Testing your changes +1. Navigate to the appropriate directory (e.g., guides are in `docs/guides`). +2. Create a new file with a URL-friendly filename (e.g., `url-friendly.md`). +3. Use Markdown to edit your document. There are many resources available online for Markdown syntax. -When working on this repo, it is advised that you review your changes locally before committing them. The `mkdocs serve` command can be used to live preview your changes (as you type) on your local machine. +### Testing Your Changes Locally -Please make sure you fork the repo and change the clone URL in the example below for your fork: +It's advised to review your changes locally before committing. Use the `mkdocs serve` command to live preview your changes on your local machine. -- Linux Mint / Ubuntu 18.04 LTS / 19.10 / 20.04 LTS: - - Preparations (only required once): +**General Steps:** + +1. Fork the repository into your own Github account. +2. Clone your fork and navigate into it. You need only do this once: ```bash git clone https://github.com/YOUR-USERNAME/docs cd docs - sudo apt install python3-pip - pip3 install -r requirements.txt ``` - - Running the docs server: +3. Install dependencies: - ```bash - mkdocs serve --dev-addr 0.0.0.0:8000 - ``` + - **Linux Mint / Ubuntu:** (18.04/20.04/22.04 LTS/19.10 and up) -- Fedora Linux instructions (tested on Fedora Linux 28): - - Preparations (only required once): + ```bash + sudo apt install python3-pip + pip3 install -r requirements.txt + ``` - ```bash - git clone https://github.com/YOUR-USERNAME/docs - cd docs - pip install --user -r requirements.txt - ``` + - **Fedora Linux:** (tested on Fedora Linux 28) + + ```bash + pip install --user -r requirements.txt + ``` - - Running the docs server: +4. Run the local docs server: ```bash mkdocs serve --dev-addr 0.0.0.0:8000 ``` -- Docker instructions: - - One-shot run: +**Docker Instructions:** +For a one-shot run with Docker, use the following command: - ```bash - docker run -v `pwd`:/opt/app/ -w /opt/app/ -p 8000:8000 -it nikolaik/python-nodejs:python3.7-nodejs16 \ - sh -c "pip install --user -r requirements.txt && \ - /root/.local/bin/mkdocs build && \ - npm ci && \ - npm test && \ - /root/.local/bin/mkdocs serve --dev-addr 0.0.0.0:8000" - ``` +```bash +docker run -v $(pwd):/opt/app/ -w /opt/app/ -p 8000:8000 \ + -it nikolaik/python-nodejs:python3.7-nodejs16 \ + sh -c "pip install --user -r requirements.txt && \ + /root/.local/bin/mkdocs build && \ + npm ci && \ + npm test && \ + /root/.local/bin/mkdocs serve --dev-addr 0.0.0.0:8000" +``` -After these commands, the current branch is accessible through your favorite browser at +After running the above, your changes will be accessible through your favorite browser at . [![Deploys by Netlify](https://www.netlify.com/img/global/badges/netlify-color-bg.svg)](https://www.netlify.com/)