How to Doc
Looking to add to the documentation? Not sure how? You've found the right place
In this page we'll go over how to add new pages, formatting, tips and tricks, guidelines etc.
First of all, if you're not familiar with markdown - every single page in the docs are written in markdown. Check out the markdown getting started page and get familiar with it.
While there is standard markdown syntax, we have a variety of markdown extensions that we use from our documentation platform MkDocs Material of which you can reference for different ways to format different elements
Making Small Page Edits¶
You will see on most pages in the upper right corner of the page there is an Edit This Page which will bring you straight to Github
When you click edit, it will bring you to Github
You can click the Preview tab to help you see what your markdown looks like
!!! info is not formatted in the Github preview, that is because it is custom MkDocs markdown formatting. Using this method works for light editing but if you plan on writing documentation regularly you should install MkDocs
You can submit a pull request or a commit to this repository and changes when approved and merged will automatically be published to this site.
Install MkDocs Material¶
Clone our documentation repository
git clone https://github.com/EQEmu/eqemu-docs-v2.git cd eqemu-docs-v2
Requires having Python installed
pip install mkdocs-material
Run the Documentation Server¶
Once it is successfully installed you can run the development docs server
mkdocs serve --dirtyreload INFO - Documentation built in 15.81 seconds INFO - [01:26:45] Serving on http://127.0.0.1:8000/ INFO - [01:26:46] Browser connected: http://127.0.0.1:8000/contributing/how-to-doc/ INFO - [01:27:13] Detected file changes
We use the
--dirtyreload for speed reasons and it's very important. Every time we make a change to a simple page we don't want to rebuild the whole entire thing. We have well over 600 pages of documentation and this would take too long.
The only time you need to re-run this command is when you make navigation changes to
mkdocs.yml. Small changes to markdown files don't require re-running
Now that you have the MkDocs Material Documentation Server running, it's a good idea to use some sort of text editor locally to edit the files.
You can use a simple text editor to edit markdown files. If you want a visual aid for what your markdown looks like you can install a markdown extension in your editor of choice like Visual Studio Code, Sublime, Jetbrains IDE's etc.
Very often you will want to use images to illustrate points in your docs. How do you upload an image? Where do you put it? Well, there are a few options.
You can upload images via commit git but its not recommended to be storing images at scale in the repository. You also want to make sure that if you are using an image that it is uploaded to a reliable image host so we don't have dead image links in the future.
The most reliable mechanism for uploading images is to use a hack that I use which is to use the Github issues page to copy and paste images into the text area and it will return a markdown code for you to use in your page.
Adding a New Page to the Navigation Tree¶
The documentation navigation tree configuration is stored in
mkdocs.yml at the top of the documentation repository in the
Do not nest pages more than 1-2 levels deep. We should not have to gopher dig for information and should be easily accessible within a simple 1-2 categorization method.
For example if your new page has something to do with inventory logic, then it should be under a top level category called Inventory not something archaic like Developer Notes -> Developer Section -> Inventory Notes -> Inventory Logic