Criando um site do zero com MkDocs¶

Preparando o ambiente¶

Antes de criarmos o site vamos preparar o ambiente, criando uma pasta para guardar os nossos projetos construidos utilizando o MkDocs

mkdir ~/Documents/MkDocs-Projetos
cd ~/Documents/MkDocs-Projetos

Iniciando um novo projeto¶

Para iniciar um novo projeto com o mkdocs devemos utilizar o seguinte comando:

mkdocs new meu_projeto

Findo o processo o comando acima gera uma saída semelhante à:

INFO    -  Creating project directory: meu_projeto
INFO    -  Writing config file: meu_projeto/mkdocs.yml
INFO    -  Writing initial docs: meu_projeto/docs/index.md

Foram criados os seguintes arquivos e diretórios:

• meu_projeto : diretório raiz do projeto
• meu_projeto/docs : diretório onde serão armazenados os arquivos e pastas utilizadas pelo MkDocs para geração do site.
• meu_projeto/mkdocs.yml : arquivo de configuração do projeto
• meu_projeto/docs/index.md : arquivo com o código da página principal

Quando criamos o novo projeto, dentro da pasta docs há apenas o arquivo index.md com algumas informações sobre o mkdocs. Este arquivo representa o index.html de um site.

O MkDocs nos fornece um built-in dev-server que nos permite visualizar um preview do nosso site. A medias que vamos adicionando novas páginas e ajustando o arquivo de configuração mkdocs.yml o conteúdo do site é automaticamente atualizado.

Para visualizarmos nosso site devemos entrar no diretório meu_projeto e executar o comando mkdocs serve

cd mkdoc
mkdocs serve

O arquivo de configuração e o conteúdo da pasta docs será analisado e as seguintes mensagens devem ser geradas:

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.30 seconds
[I 200617 14:31:32 server:334] Serving on http://127.0.0.1:8000
INFO    -  Serving on http://127.0.0.1:8000
[I 200617 14:31:32 handlers:62] Start watching changes
INFO    -  Start watching changes
[I 200617 14:31:32 handlers:64] Start detecting changes
INFO    -  Start detecting changes

Para visualizar a página devemos utilizar um browser para acessar o endereço http://127.0.0.1:8000.

Defindo o nome do site¶

Para definir o nome do nosso site devemos editar o arquivo mkdocs.yml e ajustar o valor da propriedade site_name

site_name: Meu primeiro projeto

Definindo o Tema do site¶

Há vários temas disponíveis para ser utilizados no MkDocs. Temos um artigo específico para tratar deste assunto. Por enquanto vamos utilizar um tema que já vem instalado por padrão. Usaremos o tema readthedocs. Para alterar o tema utilizado devemos ajustar o valor da propriedade theme

Precisamos editar o arquivo mkdocs.yml e ajustado de forma que fique semelhante à:

site_name: Meu primeiro projeto
theme: readthedocs

Com isto nosso site ficará semelhante à:

Adicionando novas páginas¶

Cada página do nosso site corresponde a um arquivo .md. Estes arquivos são produzidos utilizando a linguagem de marcação markdown.

Então, camos criar nossa primeira página. Crie o arquivo sobre.md dentro da pasta docs. Com teste, podemos adicionar as seguintes linhas ao arquivo:

---
title: Título da página
summary: Breve sumário da página 
authors:
    - Luis Rodrigo
date: 2020-06-17
---
# Título da Página

## Primeira seção 

## Segunda seção 

## Terceira seção 

## Referências:

* [Google](http://www.google.com.br)

Para acessar esta página podemos utilizar o endereço http://127.0.0.1:8000/sobre/. A página deve ser parecida com a imagem abaixo:

Personalizando o menu de navegação¶

O menu de navegação do site é definido ajustando-se os valores da propriedade nav. No exemplo abaixo, adicionamos ao arquivo mkdocs.yml as informações sobre um menu com duas opções, uma denominada Home que aponta para a página index.md e a segunda, denominada Sobre que aponta para a página sobre.md

site_name: Meu primeiro projeto
theme: readthedocs
nav:
- Home: index.md
- Sobre: sobre.md

A página do nosso projeto deve ter ficado semelhante à:

Building the site

1
2
3

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:

1
2
3

$ 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.

After some time, files may be removed from the documentation but they will still reside in the site directory. To remove those stale files, just run mkdocs with the --clean switch.

mkdocs build --clean

Other Commands and Options

There are various other commands and options available. For a complete list of commands, use the --help flag:

mkdocs --help

To view a list of options available on a given command, use the --help flag with that command. For example, to get a list of all options available for the build command run the following:

mkdocs build --help

Referencia:

Comentários