GitHub Actions

Publicando a sua documentação no GitHub Pages.

Summary

O DoDocs oferece um workflow reutilizável que você chama do seu próprio repositório. Não há nada para instalar: a Action baixa a imagem pronta, constrói o site e publica no GitHub Pages.

O workflow

No seu repositório, crie .github/workflows/docs.yml:

name: Docs

on:
  push:
    branches: ['main']
  workflow_dispatch:

jobs:
  build:
    permissions:
      contents: read
      pages: write
      id-token: write
    uses: thiagocajadev/do-docs/.github/workflows/build.yml@main
    with:
      mdx: 'docs' # sua pasta de Markdown
      libname: 'Meu Projeto' # nome exibido no cabeçalho
      home_redirect: '/getting-started/introduction'
      locale: 'pt-BR' # 'en' (padrão) ou 'pt-BR'
      icon: '📘'
      github: 'https://github.com/acme/meu-projeto'
      theme_primary: '#1f6feb'

  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

Faça push na main e o site é publicado. A lista completa de opções está na configuração.

Note

O GitHub Pages precisa estar habilitado no repositório, com a origem definida como GitHub Actions (Settings → Pages → Source). Sem isso, o workflow falha logo no começo.

Veja o docs.yml deste repositório para um exemplo real: é ele que publica o site que você está lendo.

Ordem da barra lateral

Por padrão, as pastas são listadas em ordem alfabética, e as páginas dentro de cada pasta seguem o nav do frontmatter.

A entrada nav_order assume essa ordem. A forma mais simples é listar as pastas, e a primeira fica no topo:

with:
  nav_order: |
    - javascript
    - typescript
    - csharp
    - sql

Para dividir a barra lateral em grupos com rótulo, use uma chave por grupo, e uma lista abaixo dela:

with:
  nav_order: |
    Estrutura:
      - html
      - css
    Programação:
      - javascript
      - typescript
      - csharp
    Banco de Dados:
      - sql

Aninhar uma pasta sob a própria chave também ordena o conteúdo dela:

with:
  nav_order: |
    Programação:
      - javascript:
          - setup
          - conventions
          - frameworks
      - typescript

Os nomes são os das pastas e páginas como aparecem na URL: quick-reference, não Quick reference.

O que você deixar de fora mantém a ordem padrão e aparece depois do que você ordenou. Ou seja, uma pasta nova continua surgindo na barra lateral sem você tocar na configuração. Os links de Anterior e Próximo no rodapé das páginas seguem essa mesma ordem.

Nomes exibidos

Os nomes das pastas são capitalizados a partir do slug, o que erra em siglas: sql vira Sql e css vira Css. A entrada nav_labels define o nome exibido, indexado pelo slug:

with:
  nav_labels: |
    sql: SQL
    css: CSS
    html: HTML
    javascript: JavaScript
    csharp: C#

Um slug que você não listar mantém a capitalização padrão. Só o texto da barra lateral muda: as URLs continuam usando o nome da pasta (/sql/readme).

Pastas sem página própria

Uma pasta que contém páginas mas não é uma página, como sql/conventions/, leva o leitor para a primeira página dentro dela. Isso vale tanto para o clique na barra lateral quanto para um link do Markdown apontando para a pasta ([conventions/](../conventions/)), que antes resultava em 404.

DoDocs v3.7.0 · Desenvolvido por @thiagocajadev · Baseado no trabalho de pmndrs/docs · Poimandres.