Mkdocs Quick Start

This article is selected from the "Markdown Practical Guide" Author: bi-xiao Annoying

Mkdocs is a static Site Builder tool developed in Python that can create project documents very simply and quickly. Mkdocs's document source code uses Markdown to write, the configuration file uses YAML to write, may one key compile into the static site.

Many open source project documents are written using Mkdocs, so it is very necessary for us to learn.

Environment Support Macos/linux/windows installation python:2.7.8 +

Installation

$ pip Install Mkdocs

View Mkdocs version

$ mkdocs-v
Mkdocs, version 0.16.3

Or

$ pip show Mkdocs
name:mkdocs
version:0.16.3
summary:project documentation with Markdown.
home-page:http://www.mkdocs.org
author:tom Christie
author-email:tom@tomchristie.com
License:bsd
Location:/library/python/2.7/site-packages
Requires:tornado, JINJA2, click, Markdown, Pyyaml, Livereload

View Mkdocs Help

$ mkdocs--help
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 builds the Mkdocs documentation (building Mkdocs documents)
  Gh-deploy  Deploy your documentation To GitHub pages (deploy documents to GitHub pages) JSON builds the       Mkdocs documentation to JSON files ... (Build the Mkdocs document into a JSON file)
  New        Create a new Mkdocs project (create a project)
  serve      Run the Builtin Development Server (start a built-in development service)

Upgrade

$ pip install-u Mkdocs

Unloading

$ pip Uninstall Mkdocs

Quick Start Create a project

 # step 1. Create a new Mkdocs project $ mkdocs New Bixiaofan info-creating Project Directory:bixiaofan info-writing Config file:bixiaofan/mkdocs.yml info-writing initial docs:bixiaofan/docs/index.md # step 2. Switch to item $ CD bixiaofan/# Step 3.
View project Structure $ tree. ├──docs # Mardown Source stacking to Docs │└──index.md└──mkdocs.yml # config file 1 directory, 2 files # view DOCS/INDEX.MD,INDEX.MD

is the default home $ cat docs/index.md # Welcome to Mkdocs for full documentation visit [mkdocs.org] (http://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 Help"-Print this help message.
    # # Project Layout mkdocs.yml # the configuration file.
        DOCS/INDEX.MD # the Documentation homepage.

... # other markdown pages, images and other files. # View configuration file Mkdocs.yml $ cat mkdocs.yml site_name:my Docs 

Start a service

$ mkdocs Serve
INFO    -  building documentation ...
INFO    -  Cleaning Site Directory
[i 170923 08:07:03 server:283] serving on http://127.0.0.1:8000
[i 170923 08:07:03 handlers:60] Start watching changes
[I 170923 08:07:03 handlers:62] Start detecting Changes
[i 17 0923 08:07:13 handlers:133] Browser connected:http://127.0.0.1:8000/

Open http://127.0.0.1:8000 in the browser, and the start effect is as shown in the following illustration:

When the server is started, the server automatically loads the changes and generates new documents when the configuration file, document directory, or theme changes.

Small sticker:

The server default address is 127.0.0.1:8000, what if the port is occupied?

The custom address is also supported, using the following command:

Mkdocs serve–dev-addr=127.0.0.1:8888

Or

Mkdocs serve-a 127.0.0.1:9999 add page

A markdown document in Mkdocs is a page after rendering, so if we want to add a page, we need to add a markdown file in the Docs directory, which can be MD, markdown, Mdown, MKDN, MKD.

Example Demo:

Step 1. Add test.md to the Docs directory

# View project structure
$ tree
.
├──docs
│   ├──index.md
│   └──test.md
└──mkdocs.yml

Description

The DOCS directory structure corresponds to the URL that generated the page, in this case the URL is:

Http://127.0.0.1:8000/
http://127.0.0.1:8000/test/

Step 2. Modify configuration file Mkdocs.yml

Site_name:markdown Practical Guide
Pages:
-Home: index.md
-Test: test.md

Description: INDEX.MD is the default homepage test.md is the new page

The effect is shown in the following illustration:

Small sticker:

The file name is not supported in Chinese, and there is no Chinese in the document path. Configuration Topics

The Mkdocs theme is configurable and the default theme is Mkdocs.

In the previous example, the Mkdocs.yml file can also be configured like this:

Site_name:markdown Practical Guide
Pages:
-Home: index.md
-Test: test.md

Theme:mkdocs

If you want to switch to another topic, just change the value of the theme.

Such as:

Site_name:markdown Practical Guide
Pages:
-Home: index.md
-Test: test.md

Theme:readthedocs

The effect is shown in the following illustration:

Topics are divided into built-in themes, Third-party themes, and custom themes, built-in topics as described above, directly configure the topic name, and if it is a third-party theme, you need to install the theme before configuring it; The custom theme is a little difficult to introduce Build Site

If you want to publish your project, you need to build the project and build a static resource site.

$ Mkdocs Build

The project structure after construction is as follows:

$ tree
.
├──docs
│   ├──index.md
│   └──test.md
├──mkdocs.yml
└──site  # build directory
    ├──css
    │   ├──highlight.css
    │   ├──theme.css
    │   └──theme_extra.css
    ├──fonts
    │   ├──fontawesome-webfont.eot
    │   ├──fontawesome-webfont.svg
    │   ├──fontawesome-webfont.ttf
    │   └──fontawesome-webfont.woff
    ├──img
    │   └──favicon.ico
    ├──index.html
    ├──js
    │   ├──highlight.pack.js
    │   ├──jquery-2.1.1.min.js
    │   ├──modernizr-2.8.3.min.js
    │   └──theme.js
    ├──mkdocs
    │   ├──js │ │   ├──lunr.min.js
    │   │ ├──mustache.min.js │ │ ├──require.js │ │   ├── Search-results-template.mustache │ │ ├──search.js │ │   └──text.js │   └── Search_index.json
    ├──search.html
    ├──sitemap.xml
    └──test
        └──index.html

After the completion of the construction of the resources are all placed in the site directory.

Small tip: Use Mkdocs build–clean to clean up some residual resources at build time. Site needs to be deployed to webserver for proper operation. Publish Project

Site Directory is the project we want to release, we can deploy the site to any place, such as: GitHub project pages.

For more, see the markdown Practical Guide Author: bi-Bug