Use Mkdocs to build a static blog on Windows

Use Mkdocs to build a static blog on Windows

Before trying to build a static blog with Hexo, recently found that there is an open-source project called Mkdocs is also a good choice to build a static blog, and it supports the markdown format, the following brief introduction of the MKDOCS environment construction process

Project Address: Https://github.com/mkdocs/mkdocs

Introduction: English version---- http://www.mkdocs.org/

Chinese Version---- http://markdown-docs-zh.readthedocs.io/zh_CN/latest/

Usage Environment: win8.1 64-bit

Basic Configuration

First, install Mkdocs via PIP

Mkdocs supports Python 2.6, 2.7, 3.3 and 3.4

Pip Install Mkdocs

Check the version after installation:

Mkdocs--version

Add path

Locate the Mkdocs.exe and add its path to the environment variable

Create a new project folder in any location, such as the name MyProject

Mkdocs New MyProject

CD MyProject

The files under the project folder are as follows:

MKDOCS.YML is a file named Index.md under the Docs folder, which displays the contents of this MD file when you start the service. (I feel this project folder is much simpler than hexo.)

Mkdocs contains a built-in server that can be used to preview the current document. Switch the current path to MyProject, enter Mkdocs serve start the service

Input in Browser http://127.0.0.1:8000/ and Open

Show:

Common commands:

Mkdocs new dirname: Creating a Project

Mkdocs Serve: Open service

Mkdocs Build: Site for building files

Mkdocs Help: View assistance

If you need to customize the page, you can modify the configuration of mkdocs.yml, in fact, mkdocs.yml the original content is not many, also a line:

Site_name:my Docs

You can change my docs to what you want, and then my docs will become what you enter after you restart the service.

Add a page

First, perform the following

Curl ' Jaspervdj.be/lorem-markdownum/markdown.txt ' > \mkdocs\myproject\docs\about.md

But the cmd indicates that curl is an invalid command, the amount ... Download Curl First

Click on the link below:

Https://curl.haxx.se/download.html

Find Win64 and suffix cab option download, unzip

Locate the AMD64 folder, and add the Curl.exe path to the environment variable

CMD on the switch to the AMD64 directory, try Curl--help, if there is a normal reply then the installation is complete

Perform the previously failed steps and add:

Curl ' Jaspervdj.be/lorem-markdownum/markdown.txt ' > \mkdocs\myproject\docs\more.md

The newly generated MD file is displayed in the Docs directory after execution is complete

If you need to add a navigation bar to the document, simply add the desired title and sort to the profile:

Site_name:my Docs

Pages:

-[Index.md, Home]

-[About.md, about]

-[More.md,more]

Theme:readthedocs

Refresh your browser to see Home and more About navigation columns

Of course, you can also switch themes, here I use the Readthedocs theme

Build site

CMD under Input:

Mkdocs Build

A directory named site is generated at this time

Note that the source code is output separately index.html and about/index.html . Other files in the theme are also copied to the site directory.

If you use the git same version control system, you may not want to submit the post-build document to the repository. You can .gitignore site/ omit the directory by adding it in.

 echo "site/" >> .gitignore

If you use a different version control system, you need to consult the relevant documentation to determine how to omit the specified directory.

After some time, files may have been removed from the source, but the related documents remain in the site directory. --clean You can remove these documents by adding parameters to the build command.

 mkdocs build –clean

发布

可以发布到github.page，新建一个github的项目并在setting上做好相关设置就可以了

需要深入研究的话可以看前面放出的链接

Jekyll is a static website builder that works together with Mkdocs to build a good blog

Refer to: http://www.ruanyifeng.com/blog/2012/08/blogging_with_jekyll.html

Use Mkdocs to build a static blog on Windows