Skip to content

Documentação

Este site foi criado usando o mkdocs.

Criar sites de documentação com MkDocs de forma simples usando markdown e ele exporta (build) em HTML.

Site oficial

https://www.mkdocs.org/

Instalação

https://www.mkdocs.org/#installation

Instalação no Linux Mint 20

1
2
3
4
5
sudo apt update
sudo apt-get install python3
sudo apt-get install python3-pip
sudo pip3 install mkdocs
sudo pip3 install mkdocs-material

Criar um site de documentação

Acessar o terminal/prompt e executar para criar o site na pasta docs

1
mkdocs new docs

O comando acima criou a estrutura:

1
2
3
4
5
6
7
8
9
mkdocs.yml
/docs/
    index.md

cd docs

mkdocs serve

http://127.0.0.1:8000/

Exemplo de site. Este site da documentação do laravel-acl

Configuraçõe a serem usadas no mkdocs.yml

https://www.mkdocs.org/user-guide/configuration

Editar o mkdocs.yml e deixar assim:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
site_name: ACL to Laravel 9
theme:
  name: 'readthedocs'
  favicon: 'img/favicon.ico'
site_url: https://ribafs.github.io/
repo_url: https://github.com/ribafs/laravel-acl/
site_description: ACL Implementation to Laravel 9
site_author: Ribamar FS
nav:
    - Início: index.md
    - Introdução: introduction.md
    - Instalação: installation.md
    - Bootstrap: bootstrap.md
    - Controllers: controllers.md
    - Views: views.md 
    - Rotas: routes.md
    - Seeders: seeders.md
    - Middleware: middleware.md
    - Provider: provider.md
    - Trait: trait.md
    - Tinker: tinker.md
    - Gerenciando: manager.md
    - Customizações: customizations.md
    - Testando: training.md
    - Erros: errors.md
    - Documentação: documentation.md
    - Licença: license.md
    - Referências: references.md
    - Testando: training.md
    - Créditos: credits.md

Editar o index.md e deixar assim:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
- ## ACL no Laravel 9
    - [Introdução](introduction.md)
    - [Instalação](installation.md)
    - [BootStrap](bootstrap.md)
    - [Controllers](controllers.md)
    - [Views](views.md)
    - [Middleware](middleware.md)
    - [Provider](provider.md)
    - [Trait](trait.md)
    - [Seeders](seeders.md) 
    - [Gerenciando](manager.md)
    - [Tinker](tinker.md)
    - [Testando o ACL](training.md)
    - [Customizando](customizations.md)
    - [Erros](errors.md)
    - [Documentação](documentation.md)
    - [Referências](references.md)
    - [Créditos](credits.md)
    - [Licença](license.md)

O index.md mostrará seu conteúdo no painel d a direita quando clicamos em Início.

Agora basta criar cada um dos arquivos com a estensão .md. Exemplo:

introduction.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# Introdução

---

- [Seção Inicial](#section-1)

<a name="section-1"></a>
## Seção Inicial

Projeto de implementação de ACL em aplicativos do Laravel from Scratch

Usando Users, Roles, Permissions, Provider, Middleware, Trait, Gates, etc

Observação: este projeto é fruto de várias pesquisas pela internet e de alguns experimentos meus

Conta com duas versões
- laravel-acl - para o laravel 9
- laravel7-acl - para o laravel 7
...

E segue.

Temas

Existem alguns temas legais. Eu gosto muito deste, readthedocs

Existem alguns temas nativos e o readthedocsc é um deles.

Para instalar um tema de terceiros:

sudo pip3 install mkdocs-material

https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes

Usando um tema

Basta trocar no mkdocs.yml:

1
2
theme:
  name: 'readthedocs'

Temas de terceiros

https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes

Extensões

https://facelessuser.github.io/pymdown-extensions/

https://facelessuser.github.io/pymdown-extensions/extensions/highlight/

Build

Quando o site estiver pronto, então exportamos em HTML para hospedar onde quisermos, com o comando

mkdocs build

Ele cria toda a estrutura HTML na pasta

/site

Limpando um build anterior mkdocs build --clean

Outros comandos

mkdocs --help

mkdocs build --help

Atualizações automáticas

Com o server ativo, após alguma alteração no mkdocs.yml ele já atualiza sem precisar de refresh

Imagens

Imagens

A pasta fica dentro da docs

1
2
3
docs/
    img/
        riba.png

Link para a imagem num arquivo .md:

1
2
![RibaFS](img/riba.png)
![RibaFS](../img/riba.png)

Referências

Markdown Cheatsheet https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

Mais detalhes http://daringfireball.net/projects/markdown/ http://github.github.com/github-flavored-markdown/

Editor online https://stackedit.io/app

Editor offline http://pad.haroopress.com/user.html