Este artículo tomado de "El Gran de rebajas" , Autor: BI problemas
MkDocs es una herramienta generadora de sitios estáticos desarrollada en Python que puede crear documentos de proyectos de manera muy fácil y rápida. El código fuente del documento de MkDocs está escrito en Markdown, y el archivo de configuración está escrito en YAML, que puede compilarse en un sitio estático con un solo clic.
Muchos documentos de proyectos de código abierto se escriben usando MkDocs, por lo que es muy necesario que aprendamos.
Medio ambiente
- Soporte macOS / Linux / Windows
- Instalar Python: 2.7.8 +
Instalar
$ pip install mkdocs
Ver la versión de mkdocs
$ mkdocs -V
mkdocs, version 0.16.3
O
$ 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: [email protected]
License: BSD
Location: /Library/Python/2.7/site-packages
Requires: tornado, Jinja2, click, Markdown, PyYAML, livereload
Ver la ayuda de mkdocs
$ 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 Build the MkDocs documentation(构建 MkDocs 文档)
gh-deploy Deploy your documentation to GitHub Pages(把文档部署到 Github Pages)
json Build the MkDocs documentation to JSON files...(把 MkDocs 文档构建成 JSON 文件)
new Create a new MkDocs project(创建一个新的项目)
serve Run the builtin development server(启动一个内置的开发服务)
Actualizar
$ pip install -U mkdocs
Desinstalar
$ pip uninstall mkdocs
Inicio rápido
Crear proyecto
# STEP 1.创建一个新的 MkDocs 项目
$ 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. 切换到项目中
$ cd bixiaofan/
# STEP 3. 查看项目结构
$ tree
.
├── docs # mardown 源码放到 docs 中
│ └── index.md
└── mkdocs.yml # 配置文件
1 directory, 2 files
# 查看 docs/index.md，index.md 是默认的首页
$ 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.
# 查看配置文件 mkdocs.yml
$ cat mkdocs.yml
site_name: My Docs
Iniciar servicio
$ 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 170923 08:07:13 handlers:133] Browser Connected: http://127.0.0.1:8000/
Abra http://127.0.0.1:8000 en el navegador , el efecto de inicio se muestra en la figura a continuación:
Una vez que se inicia el servidor, cuando cambia el archivo de configuración, el directorio de documentos o el tema, el servidor cargará automáticamente los cambios y generará nuevos documentos.
Consejos:
La dirección predeterminada del servidor es 127.0.0.1:8000, ¿qué pasa si el puerto está ocupado?
Por supuesto, las direcciones personalizadas también son compatibles, use el siguiente comando:
mkdocs serve --dev-addr = 127.0.0.1: 8888
O
mkdocs serve -a 127.0.0.1:9999
Agregar página
Un documento Markdown en MkDocs es una página después de la representación, por lo que si queremos agregar una página, primero debemos agregar un archivo Markdown en el directorio docs. La extensión del archivo puede ser md, markdown, mdown, mkdn, mkd.
Demostración de ejemplo:
PASO 1. Agregue test.md en el directorio docs
# 查看项目结构
$ tree
.
├── docs
│ ├── index.md
│ └── test.md
└── mkdocs.yml
Descripción:
La estructura de directorios de los documentos corresponde a la URL de la página generada. La URL correspondiente en este ejemplo es:
http://127.0.0.1:8000/
http://127.0.0.1:8000/test/
PASO 2. Modifique el archivo de configuración mkdocs.yml
site_name: Markdown实用指南
pages:
- 首页: index.md
- 测试: test.md
Descripción:
El efecto se muestra a continuación:
Consejos:
El nombre del archivo no admite chino por el momento, y no debe haber chino en la ruta del archivo.
Configurar tema
El tema de MkDocs es configurable, el tema predeterminado es mkdocs.
El archivo mkdocs.yml en el ejemplo anterior también se puede configurar así:
site_name: Markdown实用指南
pages:
- 首页: index.md
- 测试: test.md
theme: mkdocs
Si desea cambiar a otro tema, simplemente cambie el valor del tema.
Tales como:
site_name: Markdown实用指南
pages:
- 首页: index.md
- 测试: test.md
theme: readthedocs
El efecto se muestra a continuación:
Los temas se dividen en temas integrados, temas de terceros y temas personalizados. Los temas incorporados son los descritos anteriormente y puede configurar el nombre del tema directamente; si es un tema de terceros, primero debe instalar el tema y luego configurarlo; No por ahora
Construir sitio
Si desea publicar un proyecto, primero debe construir el proyecto y generar un sitio de recursos estático.
$ mkdocs build
La estructura del proyecto después de la construcción es la siguiente:
$ tree
.
├── docs
│ ├── index.md
│ └── test.md
├── mkdocs.yml
└── site # 构建后生成的目录
├── 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
Una vez completada la construcción, todos los recursos se colocan en el directorio del sitio.
Consejos:
- Use mkdocs build --clean para limpiar algunos recursos residuales durante la compilación.
- El sitio debe implementarse en el servidor web para ejecutarse normalmente.
Publicar proyecto
El directorio del sitio es el proyecto que queremos publicar. Podemos implementar el sitio en cualquier lugar, como por ejemplo: páginas del proyecto GitHub.
Este artículo tomado de "El Gran de rebajas" , Autor: BI problemas
