How to use MkDocs for the first time

--Environment --Windows10 Pro version 1909 - Python 3.8.5 -Click here for Python installation record - pip 20.2.3

Install mkdocs

Reference: Document creation with MkDocs --Qiita

#install
> pip install mkdocs
Collecting mkdocs
  Downloading mkdocs-1.1.2-py3-none-any.whl (6.4 MB)
     |████████████████████████████████| 6.4 MB 726 kB/s
# ...abridgement...
Successfully installed Jinja2-2.11.2 Markdown-3.2.2 MarkupSafe-1.1.1 PyYAML-5.3.1 click-7.1.2 joblib-0.17.0 livereload-2.6.3 lunr-0.5.8 mkdocs-1.1.2 nltk-3.5 regex-2020.9.27 tornado-6.0.4 tqdm-4.50.0

#Check the version
> mkdocs -V
mkdocs, version 1.1.2 from c:\path\to\venv\lib\site-packages\mkdocs (Python 3.8)

Create a project

The mkdocs.yml created when you create a project becomes the configuration file

#When you create a project with the project name "docs"
> mkdocs new docs
INFO    -  Creating project directory: docs
INFO    -  Writing config file: docs\mkdocs.yml
INFO    -  Writing initial docs: docs\docs\index.md

#A directory with the project name is created
> ls -la | grep docs
drwxr-xr-x 1 m-ukigaya 1049089 0 October 5 12:55 docs/

# index.md and mkdocs.yml is created
> find docs/ -type f
docs/docs/index.md
docs/mkdocs.yml

Build it and display it in a browser

#Go to your project directory
> cd docs

#Build
> mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: C:\path\to\docs\site
INFO    -  Documentation built in 0.11 seconds

#Start the server
> mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.12 seconds
[I 201005 13:00:32 server:335] Serving on http://127.0.0.1:8000
INFO    -  Serving on http://127.0.0.1:8000
[I 201005 13:00:32 handlers:62] Start watching changes
INFO    -  Start watching changes
[I 201005 13:00:32 handlers:64] Start detecting changes
INFO    -  Start detecting changes
[I 201005 13:00:41 handlers:135] Browser Connected: http://127.0.0.1:8000/
INFO    -  Browser Connected: http://127.0.0.1:8000/
#Ctrl when you want to stop the server+ C

Note: Start the server with mkdocs serve instead of mkdocs server. I don't need "r".

> mkdocs server
Usage: mkdocs [OPTIONS] COMMAND [ARGS]...
Try 'mkdocs -h' for help.

Error: No such command 'server'.

When [http://127.0.0.1:8000/] output by mkdocs serve is displayed on the browser, it looks like this

image.png

install the material theme

--Reference: Let's start mkdocs that can easily create documents --Qiita

Install a theme that sets the appearance. This time, I will try using material introduced on other sites. I don't care if Requirement already satisfied: ... is displayed during installation because it's like "I'm already installed".

> pip install mkdocs-material
Collecting mkdocs-material
  Downloading mkdocs_material-6.0.2-py2.py3-none-any.whl (3.9 MB)
     |████████████████████████████████| 3.9 MB 86 kB/s
# ...abridgement...
Requirement already satisfied: regex in c:\path\to\venv\lib\site-packages (from nltk>=3.2.5; python_version > "2.7" and extra == "languages"->lunr[languages]==0.5.8->mkdocs>=1.1->mkdocs-material) (2020.9.27)
Installing collected packages: Pygments, pymdown-extensions, mkdocs-material-extensions, mkdocs-material
Successfully installed Pygments-2.7.1 mkdocs-material-6.0.2 mkdocs-material-extensions-1.0.1 pymdown-extensions-8.0.1

> pip list
Package                    Version
-------------------------- ---------
...
mkdocs                     1.1.2
mkdocs-material            6.0.2
mkdocs-material-extensions 1.0.1
...
Pygments                   2.7.1

Set the theme in mkdocs.yml

  1. Open mkdocs.yml created when creating the project
  2. Add "theme:'material'"
  3. For other parts, [Let's start mkdocs that can easily create documents --Qiita](https://qiita.com/wamisnet/items/ed725d74f945f7c06b91#%E3%81%9B%E3%81%A3%E3%81 % 8B% E3% 81% 8F% E3% 81% AA% E3% 81% AE% E3% 81% A7mkdocs% E3% 82% 92material-design% E3% 81% AB% E3% 81% 97% E3% 81 % A6% E3% 81% BF% E3% 82% 88% E3% 81% 86) ... or rather copy
# Project information
site_name: 'Site name'

# Documentation and theme
docs_dir: 'docs'
theme: 'material'

# Extensions
markdown_extensions:
  - admonition
  - toc:
      permalink: '#'

Also, start the server and try to display it with a browser.

  1. Start the server with mkdocs serve
  2. When I tried to display the server with the URL output at startup, it changed like this

image.png

Recommended Posts

How to use MkDocs for the first time
Try posting to Qiita for the first time
Kaggle for the first time (kaggle ①)
How to use the generator
Kaguru for the first time
How to use the decorator
How to use the zip function
How to use the optparse module
[For self-learning] Go2 for the first time
See python for the first time
Start Django for the first time
How to use the ConfigParser module
[python] How to use the library Matplotlib for drawing graphs
I didn't know how to use the [python] for statement
How to use the Spark ML pipeline
I tried tensorflow for the first time
How to set the server time to Japanese time
[Linux] How to use the echo command
How to use the Linux grep command
[Python] Organizing how to use for statements
MongoDB for the first time in Python
How to use Pylint for PyQt5 apps
Let's try Linux for the first time
How to use "deque" for Python data
How to use the IPython debugger (ipdb)
How to use fingerprint authentication for KDE
[Introduction to Python] How to use the in operator in a for statement?
How to use machine learning for work? 01_ Understand the purpose of machine learning
How to use xml.etree.ElementTree
How to use Python-shell
How to use the C library in Python
I tried using scrapy for the first time
How to specify the launch browser for JupyterLab 3.0.0
How to use tf.data
How to use Seaboan
How to use image-match
How to use shogun
How to use Pandas 2
How to use Virtualenv
How to use numpy.vectorize
How to use Template Engine for Network Engineer
How to use pytest_report_header
Use logger with Python for the time being
[Note] Deploying Azure Functions for the first time
How to use partial
How to use Bio.Phylo
How to use the graph drawing library Bokeh
How to use SymPy
I tried python programming for the first time.
How to use x-means
How to use WikiExtractor.py
How to use data analysis tools for beginners
How to use IPython
How to use the Google Cloud Translation API
How to use virtualenv
How to use the NHK program guide API
How to use Matplotlib
[Algorithm x Python] How to use the list
How to use iptables
I tried Mind Meld for the first time
How to use numpy