Merge pull request #190 from mkasberg/readme

Improve the README

README.md

@@ -12,32 +12,43 @@ If possible, it is preferable to store image content within this repository at `
 
 ### How to add a new page
 
-Let’s consider an example. Let’s imagine we want to add a page called `Top 5 mistakes` in section `Basics` after the `Getting Started` page. This page already exists, so you can already see the results in WLED Docs, but let’s imagine the page is not there and we will go steps needed to add it:
+Let’s consider an example. Let’s imagine we want to add a page called `Top 5 mistakes` in section `Basics` after the `Getting Started` page. This page already exists, so you can already see the results in WLED Docs, but let’s imagine the page is not there and we will go over the steps needed to add it:
 
-1)	Create a file that should contain the documentation. As we want to place the new page in section `Basics` it makes sense to put this file in subfolder `docs/basics/`. In our example we call the file `top5_mistakes.md`. You can use another .md file as an example. Important is to have the following few lines at the beginning of the file:
-```
----
-title: TOP 5 mistakes
-hide:
-  # - navigation
-  # - toc
----
-```
-Don’t forget to adapt the title.
+  1. Create a file that should contain the documentation. As we want to place the new page in section `Basics` it makes sense to put this file in subfolder `docs/basics/`. In our example we call the file `top5_mistakes.md`. You can use another .md file as an example. Important is to have the following few lines at the beginning of the file:
+     ```
+     ---
+     title: TOP 5 mistakes
+     hide:
+       # - navigation
+       # - toc
+     ---
+     ```
+     Don’t forget to adapt the title.
+
+  2. Edit `mkdocs.yml` file. Take care that indentations play an important role in .yml files. Go to `nav:` section in this file and add a new line after the line `- Getting Started: basics/getting-started.md` as we want to add a new page after the `Getting Started` page. The new line must have the same indentation as the previous line and the content is `- Top 5 mistakes: basics/top5_mistakes.md`. By this we say that the new page must be called `Top 5 mistakes` and its content is in the file `top5_mistakes.md` we created before in subfolder `basics`.
 
-2)	Edit `mkdocs.yml` file. Take care that indentations play an important role in .yml files. Go to `nav:` section in this file and add a new line after the line `- Getting Started: basics/getting-started.md` as we want to add a new page after the `Getting Started` page. The new line must have the same indentation as the previous line and the content is `- Top 5 mistakes: basics/top5_mistakes.md`. By this we say that the new page must be called `Top 5 mistakes` and its content is in the file `top5_mistakes.md` we created before in subfolder `basics`.
-That is!
+That's it!
 
 ### How to add a new section
 
 It is even easier. Take a look at `nav:` section in `mkdoks.yml` file. To add a new section you just have to add a new line at a position where the new section must be. Then write a section name like this: `- Compatibility:`. TAKE CARE on indentations! After this line you can then add new pages as described above.
 
 ### How to test the representation of the documentation in web locally (on Windows, MAC OS X or Linux)
 
-You would need to install some tools:
+The easiest way to preview the documentation locally is with Docker, but you can also do it by installing mkdocs-material with Python. We'll outline both options below. In either case, you'll need a local copy of this repository to work with (either via `git clone https://github.com/Aircoookie/WLED-Docs` or by downloading the sources).
+
+#### Run Locally with Docker
+
+You must have [Docker](https://www.docker.com/products/docker-desktop/) installed. From a terminal in the `WLED-Docs` folder, run:
+
+```
+docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
+```
+
+The docker container builds and serves the site. You can see it at <http://localhost:8000>. Use <kbd>Ctrl-C</kbd> to stop the server. See the [mkdocs-material documentation](https://squidfunk.github.io/mkdocs-material/creating-your-site/#previewing-as-you-write) for more info.
 
-1) WEB Server. The probably easiest way is to use [XAMPP](https://www.apachefriends.org/index.html) to run local WEB server on your PC/Laptop. After installing you would need to start XAMPP Control Panel and run Apache Server. In the folder where XAMPP is installed to you will find a subfolder called `htdocs`. This is the content of the WEB Server and you have to put WLED Docs web pages there, for example in subfolder called `wled-docs`. Later, after generating pages using mkdocs, you will be able to access them via `http://localhost/wled-docs/site/`
-2) [Python](https://www.python.org/)
-3) [MkDocs](https://www.mkdocs.org/user-guide/installation/#mkdocs-installation)
+#### Run Locally with mkdocs
 
-Now you can downlaod WLED Docs sources from the repository to subfolder `wled-docs` in the folder `htdocs` in your XAMPP installation (or if you have git installed you can use git command to clone like `git clone --branch main https://github.com/Aircoookie/WLED-Docs`). To "compile" the resulting web pages you have to run `mkdocs build` command in the `wled-docs` folder using command line. It generates subfolder 'site' with the resulting web pages and you can access them in your browser via `http://localhost/wled-docs/site/`
+1. You must have [Python](https://www.python.org/) installed.
+2. Building the docs requires [mkdocs-material](https://squidfunk.github.io/mkdocs-material/getting-started/). This can be installed with pip or [pipx](https://github.com/pypa/pipx).
+3. From the `WLED-Docs` directory, run `mkdocs serve`. This will build the site and serve it. View the site at <http://localhost:8000>.