Sistema de Documentação

Manifesto
Configuração do Obsidian

Arquitetura do Sistema¶

A ideia geral

flowchart LR
A(Conteúdo) --> B(Controle de versão)
C(Software de edição) --> A
A --> D(Tornar acessível online)

Em detalhe:

flowchart LR
A[Obsidian] <--> B{Arquivos}
B <--> C(Github Desktop)
C <--> D{Github}
B <--> E(MkDocs)
D --> F(Github Pages)
G(Tema: MkDocs-Material) --> E
H(MkDocs-Publisher) --> E
E --> D

Componentes em detalhe¶

1. Markdown¶

Vantagens:

• É fácil de aprender e usar, o que me permite focar no conteúdo.
• É independente de plataforma, então posso continuar meu trabalho em qualquer dispositivo.
• É ideal para controle de versão, o que me permite rastrear e gerenciar alterações.
• É à prova de futuro e não proprietário, o que me dá a certeza de que meu trabalho permanecerá acessível a longo prazo.

Markdown

2. Obsidian¶

• Posso armazenar meus dados localmente e editá-los offline, o que me dá flexibilidade e controle.
• Posso vincular e conectar arquivos facilmente, o que me ajuda a organizar informações complexas.
• Posso marcar arquivos com tags e gerenciá-los facilmente, o que me dá uma dimensão adicional de organização.
• Posso visualizar meus dados graficamente, o que me ajuda a identificar padrões e relacionamentos.
• Posso estender a funcionalidade do Obsidian com plugins, o que me permite adaptar a ferramenta às minhas necessidades específicas.

3. Git e Github¶

Vantagens:

• Controle de versão: Cada alteração é documentada e pode ser rastreada a qualquer momento, o que me ajuda a evitar erros e a manter o controle.
• Colaboração: Várias pessoas podem trabalhar na documentação simultaneamente, o que me dá a oportunidade de integrar feedback e contribuições de outras pessoas.
• Backup: Minha documentação está segura e é regularmente copiada, o que me dá a certeza de que meu trabalho não será perdido.

4. Github Desktop¶

Vantagens:

• Fácil de usar, o que facilita o uso do Git.
• Não são necessários conhecimentos de linha de comando, o que me poupa tempo e esforço.
• Simplifica meu fluxo de trabalho, o que me permite focar na criação de conteúdo.

5. MkDocs¶

Vantagens:

• Criação de sites simples, o que me permite publicar minha documentação de forma rápida e fácil.
• Atualização rápida, o que me permite ver as alterações em tempo real.
• Layout consistente, o que garante uma apresentação profissional e uniforme da minha documentação.
• Pré-visualização offline, o que me permite verificar minha documentação antes de publicá-la.

6. Github Pages¶

Vantagens:

• Hospedagem gratuita, o que me permite publicar minha documentação sem custos adicionais.
• Publicação fácil, o que me livra da implementação técnica da publicação.
• Confiável, o que me dá a certeza de que minha documentação estará sempre disponível.

7. MkDocs-Material¶

Vantagens:

• Design moderno, o que faz minha documentação parecer profissional e atual.
• Personalizável, o que me permite adaptar o layout às minhas necessidades específicas.
• Fácil de usar, o que facilita o uso da documentação.

8. MkDocs-Publisher¶

Vantagens:

• Integração simplificada com Obsidian: Ajuste automático da sintaxe Markdown do Obsidian (Callouts, Wikilinks, etc.).
• Metadados expandidos: Integração de tags e categorias do frontmatter do Obsidian.

Fluxo de trabalho¶

1. Crio e edito arquivos Markdown com um editor de texto (opcionalmente Obsidian).
2. Salvo os arquivos Markdown localmente.
3. Envio minhas alterações para o repositório Git com o Github Desktop.
4. Gero automaticamente o site com o MkDocs.
5. Publico o site com o Github Pages.

Sistema de arquivos¶

/docs/     (Aqui estão meus arquivos Markdown)
/site/     (Aqui o site é gerado)
license    (Informações de licença)
mkdocs.yml (Arquivo de configuração para MkDocs)
readme.md  (Arquivo para descrever o repositório)

Alternativas para criação de conteúdo¶

1. Wordpress: O conteúdo pode ser criado no Wordpress como uma página.
2. Arquivo de texto, arquivo Word: O conteúdo pode ser criado como um arquivo de texto, arquivo Word (ou em outros formatos típicos).

Nesses casos, posso então integrar o conteúdo ao sistema.