Código-fonte e documentação para página oficial da documentação hospedado na docs.adonisjs.com
Siga os passos mencionados abaixo para configurares o teu projeto local:
- Bifurque o repositório
- Empurre o repositório no teu local
- Instale todas as dependências usando
npm install. - Inicie o servidor de desenvolvimento da AdonisJS usando
node ace serve --watch
Nós não seguimos nenhum processo para transformar documento markdown em HTML. No lugar disto, compilamos os ficheiros em cada requisição de página. Isto garante que não tenhamos de executar nenhum compilador de fundo para compilar o markdown e depois recompilar tudo numa única mudança. O processo é tão simples quanto:
--> Nova requisição de HTTP --> Encontrar o ficheiro markdown para a URL --> Compilá-lo e servi-lo
As seguintes variáveis de ambiente são obrigatórias para iniciar o servidor de desenvolvimento ou criar uma construção de produção:
PORT=3333
HOST=0.0.0.0
NODE_ENV=development
APP_KEY=iPbHJ0Wdr8_hA4DLTj83lKedQP9I5rJO
CACHE_VIEWS=false
DEBUG_DOCS=true
ALGOLIA_API_KEY=
COPY_REDIRECTS_FILE=false
A variável de ambiente ALGOLIA_API_KEY é opcional e exigida apenas se quiseres ativar a pesquisa de conteúdo.
Se estiveres a implementar em produção uma versão traduzida da documentação, então defina a COPY_REDIRECTS_FILE=false. Já que o ficheiro de redirecionamentos é apenas aplicável para a documentação oficial para evitar quebrar as URLs de previw.adonisjs.com.
O conteúdo de markdown é guardado dentro do diretório content e cada tipo de documentação (nós as chamamos de zonas) tem sua própria sub-pasta.
A navegação para cabeçalho da página e barra lateral é orientada pelo ficheiro menu.json dentro de cada sub-diretório da zona:
content
├── cookbooks
│ ├── menu.json
├── guides
│ ├── menu.json
├── reference
│ └── menu.json
└── releases
├── menu.json
O ficheiro menu.json tem a seguinte estrutura:
{
"name": "Database",
"categories": [
{
"name": "root",
"docs": [
{
"title": "Connection",
"permalink": "database/connection",
"contentPath": "database/connection.md",
}
]
}
]
}- O objeto de alto nível é nome do grupo. Tu podes ter um ou mais grupos dentro duma zona e serão listados num menu deslizante na navegação do cabeçalho.
- Se não houver nenhum grupo. Tu podes nomeia-lo como
root. - Cada grupo pode ter um ou mais
categories. As categorias são listadas dentro da barra lateral. - A categoria com nome
rootnão será impressa no HTML. - Cada categoria pode ter um ou mais
docs. - A documentação ainda tem um
title,permalinke o caminho para o ficheiro de conteúdo. O caminho é relativo da zona raiz.
Nós fazemos uso dum módulo @dimerapp/content escrito por nós para transformar o markdown em HTML usando modelos de marcação de Edge no meio.
Nós começamos primeiro por converter o Markdown numa Árvore de Sintaxe Abstrata e depois transformamos cada nó Árvore de Sintaxe Abstrata usando os modelos de marcação de Edge. Isto permite separar o markdown personalizado. Consulte o diretório ./resources/views/elements para veres como estamos a usá-lo.
Os blocos de código são gerados usando o shiki. O módulo usa a gramática e temas do Visual Studio Code para processar os blocos de código. Além disto, os blocos de código são processados no backend e cliente recebe o HTML formatado.
O módulo @dimerapp/content não vem com nenhuma interface da linha de comando ou opções sobre como o conteúdo deveria ser estruturado.
Então temos de configurar o módulo @dimerapp/content. Isto é feito dentro do ficheiro start/content.ts, que depende do ficheiro config/markdown.ts.
Os estilos são escritos em CSS puro e armazenados dentro do diretório ./resources/css. Para organizarmos um pouco as coisas, temos de separá-los dentro de vários ficheiros .css.
Nós também fazemos uso de alpine.js para adicionar pequenos componentes interativos, como deslize da navegação de cabeçalho e a alternância do grupo de código.
O @hotwire/turbo é usado para navegar entre as páginas sem fazer uma atualização completa.
O redesenho das páginas de HTML reinicia a posição do deslocamento da barra lateral, o que é um pouco irritante. Então fazemos uso de eventos de turbo turbo:before-render e turbo:render para armazenar a posição da barra lateral e então restaurá-lo depois da navegação.
No primeiro carregamento da página, deslocamos o item da barra lateral ativo para a visão usando o método scrollIntoView.
Execute o seguinte comando para criar a construção de produção.
npm run buildA saída é escrita no diretório public e podes servi-lo em qualquer hospedeiro capaz de servir ficheiros estáticos.
A página oficial está hospedada na pages.cloudflare.com
A variável de ambiente ALGOLIA_API_KEY é opcional e exigida apenas se quiseres ativar a pesquisa de conteúdo.
Se estiveres a implementar em produção uma versão traduzida da documentação, então defina a COPY_REDIRECTS_FILE=false. Já que o ficheiro de redirecionamentos é apenas aplicável para a documentação oficial para evitar quebrar as URLs de previw.adonisjs.com.
Tu estás livre de bifurcar este repositório e traduzir a documentação para diferentes idiomas e publicá-los num sub-domínio separado.
Desmentido: A documentação traduzida é considerada um esforço da comunidade. A página e traduções nunca serão suportadas ou mantidas pela equipa principal.
- Notifique a todos sobre a documentação traduzida nesta questão fixada.
- Nós podemos entregar-te um sub-domínio para o idioma uma vez que tiveres traduzido mais de 50% da documentação.
- A medida que a documentação for atualizada na página oficial, deixaremos uma ligação para o pedido de atualização na questão fixada e podes empurrar de volta aquelas mudanças.
- Nós recomendados não localizar as URLs. Apenas traduza o conteúdo da documentação.
- Sinta-se livre para enviar um pedido de atualização para a Algolia para indexar o página traduzida. Cá está uma referência para a configuração da algolia da página oficial.