| 1 |
This folder contains the source files for http://simplehtmldom.sourceforge.net/, |
| 2 |
the project page for PHP Simple HTML DOM Parser. |
| 3 |
|
| 4 |
Source files are written in Markdown: https://en.wikipedia.org/wiki/Markdown |
| 5 |
|
| 6 |
Site data is generated by MkDocs, a lightweight static site generator for project |
| 7 |
documentation: https://www.mkdocs.org/ |
| 8 |
|
| 9 |
# Folder structure |
| 10 |
|
| 11 |
`custom_theme` : Contains customizations to the theme provided by MkDocs. |
| 12 |
`docs` : Contains the source files for the project page (the actual pages). |
| 13 |
`site` : Contains the output files for the project page when build with MkDocs. |
| 14 |
`extra.css` : Customizations to the styles provided by MkDocs. |
| 15 |
`mkdocs.yml` : The configuration file that is used by MkDocs to generate pages. |
| 16 |
|
| 17 |
# Adding new pages |
| 18 |
|
| 19 |
Place new files in `source`. Use subfolders (as few levels as possible) to |
| 20 |
separate categories. |
| 21 |
|
| 22 |
Files added to the manual will **not** appear on the project page automatically. |
| 23 |
All pages need to be specified in the _mkdocs.yml_ file under "nav:". Simply add |
| 24 |
the relative path to the new file where appropriate. |
| 25 |
|
| 26 |
Note: Files are not added automatically because they are sorted by name if not |
| 27 |
specified manually. Since readability is key factor for manuals, the files must |
| 28 |
be sorted in a way that makes it clear to users. |
| 29 |
|
| 30 |
# Setting up MkDocs |
| 31 |
|
| 32 |
The installation instructions for MkDocs are provided on their homepage: |
| 33 |
https://www.mkdocs.org/#installation |
| 34 |
|
| 35 |
MkDocs automatically builds the project based on the _mkdocs.yml_ file. Find the |
| 36 |
specification for this file at https://www.mkdocs.org/user-guide/configuration/. |
| 37 |
|
| 38 |
# Building project pages |
| 39 |
|
| 40 |
The build process depends on your installation of MkDocs. Typically MkDocs is |
| 41 |
made available via the command line. |
| 42 |
|
| 43 |
## Step 1 - Check your version of MkDocs |
| 44 |
|
| 45 |
To check your version of MkDocs run this command: |
| 46 |
|
| 47 |
`mkdocs --version` or |
| 48 |
`python3 -m mkdocs --version` |
| 49 |
|
| 50 |
Should return `version 1.0.4` or higher. If it doesn't make sure to install the |
| 51 |
latest version using `pip install mkdocs` or `python3 -m pip install mkdocs`. If |
| 52 |
you don't have pip installed, install it via package manager or follow the |
| 53 |
instructions at https://pip.pypa.io/en/stable/installing/ |
| 54 |
|
| 55 |
## Step 2 - View the project locally |
| 56 |
|
| 57 |
MkDocs allows you to view the project files in a browser on your local machine: |
| 58 |
|
| 59 |
`mkdocs serve` or |
| 60 |
`python3 -m mkdocs serve` |
| 61 |
|
| 62 |
If the process is successful you can access the site at http://127.0.0.1:8000. |
| 63 |
|
| 64 |
## Step 3 - Build the project |
| 65 |
|
| 66 |
If you are satisfied with the results of the project, build the final project |
| 67 |
with this command: |
| 68 |
|
| 69 |
`mkdocs build` or |
| 70 |
`python3 -m mkdocs build` |
| 71 |
|
| 72 |
Find the output files in the `site` folder. |
