dodocs

Escrevendo

Frontmatter, Markdown e os componentes que o DoDocs entende.

Summary

O DoDocs aceita todo o GitHub Flavored Markdown, mais alguns componentes próprios, descritos nas páginas seguintes.

Nesta página

Na sua pasta de documentação, crie qualquer caminho/para/documento.md:

---
title: Meu documento
description: Uma linha sobre o que ele cobre.
nav: 0
---

O conteúdo, em Markdown.

O caminho do arquivo vira a URL, e a pasta vira a seção da barra lateral. Nada mais precisa ser registrado.

Frontmatter

Todas as chaves são opcionais.

  • title: se ausente, o nome do arquivo é usado (meu-documento vira "Meu documento").
  • description: aparece abaixo do título e nos metadados de compartilhamento.
  • nav: ordem da página dentro da pasta. Números menores vêm primeiro. Sem nav, a ordem é alfabética.
  • image: imagem usada nos metadados. Caminho relativo ao arquivo (foto.png, ../foto.png), absoluto (/foto.png) ou uma URL completa.
  • sourcecode: caminho do arquivo-fonte que a página descreve. Vira um link no rodapé.
Note

nav ordena apenas as páginas dentro de uma pasta. Para ordenar as pastas em si, e para agrupar a barra lateral, use nav_order.

title e description aceitam Markdown:

---
title: "O componente `Intro`"
description: Abre uma página com **destaque**, aceita `código` e links
---
Note

Se o título começar com crase, envolva em aspas. Sem elas, o YAML não entende.

.md ou .mdx

Os dois funcionam, na mesma pasta, misturados. A extensão decide o que o arquivo pode fazer.

ExtensãoUse quandoO que você ganha
.mdMarkdown comum, o caso da maioriaTodo o Markdown padrão, mais HTML cru como <details>
.mdxVocê quer componentes na páginaTudo do .md, mais <Intro>, <Hint>, <Mermaid> e afins

Na dúvida, use .md. Renomeie para .mdx no dia em que precisar de um componente.

A diferença prática: em .md, escrever <div> produz uma div de verdade. Em .mdx, uma tag com inicial maiúscula é lida como componente, e o HTML cru precisa ser válido para JSX.

Markdown

Além do GFM, você pode usar HTML padrão, com suporte a Tailwind:

<div className="rounded-lg border border-outline-variant p-4">
  <p className="text-sm text-on-surface-variant">Uma caixa, montada na mão.</p>
</div>

resultado:

Uma caixa, montada na mão.

Note

As cores vêm do react-mcu, geradas a partir da sua cor de destaque. Por isso text-on-surface-variant acima funciona em tema claro e escuro sem você fazer nada.

As páginas seguintes documentam cada componente disponível.

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