Hey there,
I have been doing R&D for upcoming project which seem relatively large compared to other works . So i was looking for a document preparation tool to organize everything. At first google docs was a good option which was very quick , easy to use and maintain. But as the content of the research increases it becomes harder to track each points.
so I came up with MkDocs which seems good.
Let us see how to set it up in no time.
Introduction
- MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation.
- Documentation source files are written in Markdown, and configured with a single YAML configuration file.
- The built-in dev-server allows you to preview your documentation as you're writing it. It will even auto-reload and refresh your browser whenever you save your changes.
Manual Installation
$ python --version
Python 3.8.5
$ pip --version
pip 20.3.3 from C:\Users\username\Anaconda3\lib\site-packages\pip (python 3.8)
pip install --upgrade pip
Installing MkDocs
pip install mkdocs
$ mkdocs --version
mkdocs, version 1.1.2
Getting Started
mkdocs new demo
cd demo
- There's a single configuration file named mkdocs.yml, and a folder named docs that will contain your documentation source files.
Right now the docs folder just contains a single documentation page, named index.md.
MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it.
Make sure you're in the same directory as the mkdocs.yml configuration file, and then start the server by running the mkdocs serve command:
$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes
Open up http://127.0.0.1:8000/ in your browser, and you'll see the default home page being displayed:
The dev-server also supports auto-reloading
Open the docs/index.md document in your text editor of choice, change the initial heading to your choice, and save your changes
Now try editing the configuration file: mkdocs.yml. Change the site_name setting to what you always wanted to view and save the file.
Adding pages
- As our documentation site will include some navigation headers, you may want to edit the configuration file and add some information about the order, title, and nesting of each page in the navigation header by adding a nav setting:
site_name: MkLorum
nav:
- Home: index.md
- About: about.md
- Save your changes and you'll now see a navigation bar with Home and About items on the left as well as Search, Previous, and Next items on the right.
Theming our documentation
- Now change the configuration file to alter how the documentation is displayed by changing the theme. Edit the mkdocs.yml file and add a theme setting:
site_name: MkLorum
nav:
- Home: index.md
- About: about.md
theme: readthedocs
Building the site
- That's looking good. You're ready to deploy the first pass of your MkLorum documentation. First build the documentation:
mkdocs build
- This will create a new directory, named site. Take a look inside the directory:
$ ls site
about fonts index.html license search.html
css img js mkdocs sitemap.xml
- Notice that your source documentation has been output as two HTML files named index.html and about/index.html.
- You also have various other media that's been copied into the site directory as part of the documentation theme.
You even have a sitemap.xml file and mkdocs/search_index.json.
-
If you're using source code control such as git you probably don't want to check your documentation builds into the repository. * Add a line containing site/ to your .gitignore file.
Other Commands and Options
mkdocs --help
mkdocs build --help
For more information check out official docs : Officil site
If you have more suggestions about document preparation please consider sharing your thoughts in the comment section.
Thats it for now. Hasta Pronto ! 🙌🙌
Top comments (0)