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
Installation
To install MkDocs, run the following command from the command line:
pip install mkdocs
> mkdocs -h Usage: mkdocs [OPTIONS] COMMAND [ARGS]... MkDocs - Project documentation with Markdown. Options: -V, --version Show the version and exit. -q, --quiet Silence warnings -v, --verbose Enable verbose output -h, --help Show this message and exit. Commands: build Build the MkDocs documentation gh-deploy Deploy your documentation to GitHub Pages new Create a new MkDocs project serve Run the builtin development server
> mkdocs --version mkdocs, version 1.3.1 from c:\users\jack\python38-venv\env\lib\site-packages\mkdocs (Python 3.8)
For more details, see the Installation Guide.
Creating a new project
Getting started is super easy. To create a new project, run the following command from the command line:
mkdocs new my-project cd my-project
$ tree . ├── docs │ └── index.md └── mkdocs.yml
There’s a single configuration file named mkdocs.yml, and a folder named docs that will contain your documentation source files (docs is the default value for the docs_dir configuration setting). Right now the docs folder just contains a single documentation page, named index.md.
ไฟล์ mkdocs.yml
site_name: My Docs
ไฟล์ docs/index.md
# Welcome to MkDocs
For full documentation visit [mkdocs.org](https://www.mkdocs.org).
## Commands
* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs -h` - Print help message and exit.
## Project layout
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.
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 INFO - Documentation built in 0.24 seconds INFO - [21:14:45] Watching paths for changes: 'docs', 'mkdocs.yml' INFO - [21:14:45] Serving on http://127.0.0.1:8000/
Open up http://127.0.0.1:8000/ in your browser, and you’ll see the default home page being displayed:
Fenced code blocks
The fenced code blocks extension adds an alternate method of defining code blocks without indentation.
The first line should contain 3 or more backtick (`) characters, and the last line should contain the same number of backtick characters (`):
``` Fenced code blocks are like Standard Markdown’s regular code blocks, except that they’re not indented and instead rely on start and end fence lines to delimit the code block. ```
With this approach, the language can optionally be specified on the first line after the backticks which informs any syntax highlighters of the language used:
```python
def fn():
pass
```
```sql
SELECT * FROM FOO
```
```c
main() {
print('Hello');
}
```
Note that fenced code blocks can not be indented. Therefore, they cannot be nested inside list items, blockquotes, etc.
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.
echo "site/" >> .gitignore
If you’re using another source code control tool you’ll want to check its documentation on how to ignore specific directories.