17. MkDocs Tutorial

I will explain on how I build this site and host it on GitLab Pages/GitHub Pages.

17.1 Basic

This is a static website generated by static site generator tool called MkDocs. We can write all pages/contents in MarkDown. MkDocs will take it and generate html files and prepare the website. Ref: https://www.mkdocs.org/getting-started/

17.2 Installation on Ubuntu

( This can be done on MS Windows too. )

sudo apt install python3-pip
python3 -m venv ~/sandbox/
. ~/sandbox/bin/activate
python3 -m pip install mkdocs "mkdocstrings[python]" mkdocs-material mkdocs-enumerate-headings-plugin

mkdocs new my-project
cd my-project
ls -l

This automatically create ./docs and mkdocs.yml mkdocs.yml is configuration file. mkdocs reads the .md files from ./docs folder to generate .html file. Hence, follow the system.

mkdocs serve above serve command will run local web server, which we can access it. This does not generate the files for site.

mkdocs build once we are happy with test server, we can issue build. build produce the entire site in the folder ./site. However, since I am going to host it on gitlab, and, gitlab expects the site to be in ./public folder, I just add instruction in mkdocs.yml to output into ../public instead of default ./site folder.

17.3 Hosting on GitLab

Reference : https://docs.gitlab.com/ee/user/project/pages/getting_started/pages_from_scratch.html

go to the webview of your repo go to repo-> settings -> pages and see the pages URL. It is the webpage url

GitLab uses ./.gitlab-ci.yml for setting the server. if not preset, please create it. It always expects the files from ./public folder

# ./.gitlab-ci.yml
pages:
  stage: deploy
  script:
    - echo 'nothing ...'
  artifacts:
    paths:
      - public
  only:
    #- master
    - test

above file tells the GitLab pipeline pick the content from branch 'test' (that is my branch, u can use any branch, even master) and deploy it.

The job runs every time we commit to the repo. i.e., if that yml file exists, it is an instruction to start a pipeline job. What job has to do is written in the yaml file. Here we are doing 'deploy' of the website.

18. Advanced features of MkDocs

18.1 Enumerate Headings

Automatically generate Numbers for Heading (H1/H2) Plugin Tutorial Install the plugin using pip:

python -m pip install markdown
python -m pip install pymdown-extensions
python -m pip install mkdocs-enumerate-headings-plugin
python -m pip install mkdocs-print-site-plugin
#python -m pip install mkdocs-bootswatch # for theme: slate
# for ~~ strike through~~
python3 -m pip install git+git://github.com/aleray/mdx_del_ins.git

Next, add the following lines to your mkdocs.yml:

plugins:
  - search
  - enumerate-headings

markdown_extensions:
    - del_ins # for strike thorugh extention

18.2 Site print

To print whole site in a URL http://127.0.0.1:8000/print_page/ https://timvink.github.io/mkdocs-print-site-plugin/
python -m pip install mkdocs-print-site-plugin Next, add the following lines to mkdocs.yml.

plugins:
  - search
  - print-site

http://127.0.0.1:8000/print_page/ ⚠ Make sure to put print-site to the bottom of the plugin list.
This is because other plugins might alter your site (like the navigation),
and you want these changes included in the print page.

Ref: https://developers.google.com/search/docs/advanced/sitemaps/build-sitemap#addsitemap  
publish to google  
https://www.google.com/ping?sitemap=https://prabhu-yu.github.io/sitemap.xml  

And create a robots.txt
docs/robots.txt  
Sitemap: https://prabhu-yu.github.io/sitemap.xml  

18.3 removing the TOC

On some pages, we don't need TOC (for example, the landing page index.html).
We can create template file and mention the template meta data in .md file.
How to do this is given in below link. I have done this for index.md file
and created custom_theme/no_toc.html file for this. Yes, this needs
mkdocs.yml change too since we need to add custom_theme dir in .yml file.

18.4 Adding comments section

I use utteranc for this. Add your repo name in following page and get the script. https://utteranc.es/

Then go to custom_theme/main.html and add the script into the footer sections.
Rebuild the docs ands serve (if it does not rebuild automatically)
some time, it will take while to show comments section... so wait..

18.5 References

• About template file and removing TOC from html page:
  https://github.com/mkdocs/mkdocs/pull/917