Logo-Docs

KO | EN

gitlite — search

#self-hosted #framework #computer-vision #api #mysql #rust #typescript #golang #terminal #bash

(★ 9)

Projeto para criação de um portal que permite publicar documentações em Markdown, tornando-as acessíveis em organizações ou publicamente. Também oferece ferramentas para visualização temporária de Markdown e formatação de JSON e dicionários Python.

File Explorer

ZIP Download

- aprimorar-markdown-estatico.js
- formatador-dict-python.js
- formatador-json.js
- indice-conteudo.js
- menu-responsivo.js
- mermaid-init.js
- visualizador-markdown.js
- default.conf
- formatador-dict-python.md
- formatador-json.md
- visualizador-markdown.md
- baixar_recursos_frontend.py
- entrada_producao.py
- preparar_portal.py
- extra.css
.dockerignore
.gitignore
docker-compose.yml
docker-stack.yml
Dockerfile
ESPECIFICACAO.md
LICENSE
mkdocs.yml
NOTICE
README.md
requirements.txt

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Portal estático para publicar documentação Markdown de projetos internos, com
busca, navegação isolada por projeto e ferramentas temporárias de Markdown,
JSON e dict Python.

## Contexto e finalidade

O projeto surgiu da necessidade de divulgar documentação Markdown dentro da
empresa sem exigir que as pessoas instalem ferramentas ou conheçam a sintaxe do
formato. Para quem não trabalha com desenvolvimento, abrir um arquivo `.md`
cru geralmente dificulta a leitura: títulos, tabelas, avisos, código e
diagramas deixam de ter a apresentação que dá contexto ao conteúdo.

O portal transforma esses arquivos em páginas pesquisáveis e navegáveis, para
que áreas de suporte e demais equipes consultem a documentação no navegador.
As ferramentas extras seguem a mesma ideia: permitem visualizar Markdown e
formatar JSON ou dict Python localmente, sem que o funcionário precise procurar
serviços na internet para tarefas pontuais. Isso é especialmente útil para
equipes de suporte que manipulam conteúdos técnicos, mas não têm familiaridade
com programação.

## Acesso e evolução

O portal não implementa autenticação, permissões ou segmentação de conteúdo.
Todos os projetos publicados ficam acessíveis a qualquer pessoa que tenha
acesso ao endereço interno. Portanto, não inclua documentação que exija
restrição de acesso na instância atual.

Uma evolução futura possível é segmentar a documentação por setor, equipe ou
pessoa, adicionando um modelo de autorização adequado às necessidades da
empresa. Essa capacidade está fora do escopo atual, que prioriza publicação e
consulta simples de conteúdo interno.

## Desenvolvimento local

No VS Code, selecione o interpretador `.venv\Scripts\python.exe`. Não é
necessário alterar o `PATH` do Windows nem instalar dependências globalmente.

No terminal PowerShell integrado, na raiz do repositório:

```powershell
py -3.11 -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
.\.venv\Scripts\python.exe scripts\baixar_recursos_frontend.py
.\.venv\Scripts\python.exe scripts\preparar_portal.py
.\.venv\Scripts\mkdocs.exe serve
```

O site fica disponível em `http://127.0.0.1:8000`. O servidor local recompila
o site ao salvar arquivos. Para executar uma geração estrita sem servidor:

```powershell
.\.venv\Scripts\python.exe scripts\preparar_portal.py
.\.venv\Scripts\mkdocs.exe build --strict
```

## Container

```powershell
docker compose up -d --build
docker compose ps
```

O acesso padrão é `http://localhost:8085`. Para outra porta:

```powershell
$env:DOCS_PORT = '8090'
docker compose up -d --build
```

## Conteúdo

Cada projeto fica em `conteudo/projetos/<slug>/`, com `README.md` como página
inicial e `docs/` para as demais páginas e recursos. O slug aceita letras
minúsculas, números e hífens. Links iniciados por `docs/` no README são
ajustados na preparação.

Por segurança, o Git ignora todo conteúdo de `conteudo/projetos` exceto
`conteudo/projetos/exemplo`. Documentação local não será incluída em commits
acidentalmente. Para publicar um novo projeto, crie sua pasta, copie os
arquivos Markdown e execute novamente a preparação local ou o build Docker.

## Ferramentas

O menu oferece visualização temporária de Markdown, formatação de JSON e
formatação segura de dict Python. O conteúdo é processado no navegador e não é
enviado ou persistido pelo portal.

A pasta `vendor/` é um cache local gerado por `scripts/baixar_recursos_frontend.py`.
Ela não é versionada nem enviada ao contexto Docker. Os recursos são baixados
na primeira execução da aplicação e reutilizados enquanto o ambiente existir.

## Deploy em Linux

O ambiente usa dois serviços: `aplicacao`, que executa Python/MkDocs e gera o
site, e `nginx`, que publica os arquivos gerados. Ambos são compatíveis com
Docker Engine e Docker Compose em Linux.

```bash
git clone <URL_DO_REPOSITORIO> logo-docs
cd logo-docs
docker compose up -d --build
docker compose ps
```

A porta padrão é `8085`. Para alterá-la, use `DOCS_PORT=8090 docker compose up -d --build`.
O volume nomeado `logosystem-documentacao-conteudo` guarda os projetos e o
volume `logosystem-documentacao-site` guarda o resultado publicado.

## Conteúdo privado e volumes

Na primeira inicialização, o serviço `aplicacao` copia o projeto `exemplo` para
o volume de conteúdo, caso ele esteja vazio. Depois disso, o volume é a fonte
persistente dos documentos; apagar ou substituir o exemplo não exige reconstruir
a imagem.

Para substituir o exemplo por documentos privados, copie o conteúdo para o
volume através do contêiner da aplicação. Por exemplo, a partir de uma pasta
local `meus-projetos`:

```bash
docker compose exec aplicacao rm -rf /app/conteudo/projetos/exemplo
docker cp ./meus-projetos/. logosystem-documentacao-aplicacao:/app/conteudo/projetos/
```

O monitor da aplicação detecta a alteração e regenera o portal automaticamente.
O `.gitignore` protege os projetos privados; somente `exemplo` é versionado.
Eles podem permanecer exclusivamente no volume nomeado do servidor.

## Atualização em produção

Para atualizar código, layout ou ferramentas:

```bash
git pull --ff-only
docker compose up -d --build
```

Não execute `scripts/preparar_portal.py` no Nginx. A aplicação já executa esse
processo automaticamente sempre que detectar alterações no volume. Para forçar
uma geração manual:

```bash
docker compose exec aplicacao python scripts/preparar_portal.py
```

O conteúdo é atualizado em tempo real, sem reconstruir a imagem. Alterações no
repositório do código continuam exigindo `git pull` e `docker compose up -d
--build`; o volume de documentos não é apagado nesse processo.

Na primeira execução, a aplicação precisa de acesso à Internet para baixar os
recursos frontend em `vendor/`. Depois do download, eles ficam no ambiente da
aplicação e não são necessários no Git.

## Deploy no Docker Swarm e Portainer

Para o Swarm, use `docker-stack.yml`. Gere e publique a imagem da aplicação em
um registry acessível pelo nó do Swarm:

```bash
docker build -t registry.exemplo.local/logosystem/logo-docs:1.0.0 .
docker push registry.exemplo.local/logosystem/logo-docs:1.0.0
```

No Portainer, crie uma Stack usando `docker-stack.yml` e defina `DOCS_IMAGE`
com o nome completo e a tag da imagem. Defina também `DOCS_PORT` se quiser
alterar a porta publicada; o padrão é `8085`.

O acesso externo será `http://IP_DO_SERVIDOR:8085` ou a porta definida em
`DOCS_PORT`. Não é necessário configurar `site_url` para acesso por IP: o
portal usa links relativos e o Nginx escuta em todas as interfaces.

Pela CLI, o equivalente é:

```bash
export DOCS_IMAGE=registry.exemplo.local/logosystem/logo-docs:1.0.0
export DOCS_PORT=8085
docker stack deploy -c docker-stack.yml logosystem
```

O conteúdo fica nos volumes nomeados `logosystem_documentacao_conteudo` e
`logosystem_documentacao_site`. Use o console do serviço `aplicacao` no
Portainer para remover o exemplo e inserir os projetos privados. Pela CLI,
identifique o contêiner da tarefa e copie os arquivos:

```bash
docker ps --filter label=com.docker.swarm.service.name=logosystem_aplicacao
docker cp ./meus-projetos/. <CONTAINER_DA_APLICACAO>:/app/conteudo/projetos/
```

O serviço detecta a alteração e publica o conteúdo automaticamente. Em um
Swarm com mais de um nó, volumes locais ficam presos ao nó em que foram
criados; mantenha os serviços nesse nó ou use um driver de volume compartilhado.

Para atualizar a aplicação, publique uma nova tag e atualize `DOCS_IMAGE` na
Stack. Os volumes de documentos não são recriados durante a atualização.

Logo-Docs

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README