mdBook - Ferramenta de linha de comando para criar livros com Markdown
(rust-lang.github.io)- Quando é preciso distribuir documentação e tutoriais em formato de livro, o mdBook 0.5.3 oferece escrita baseada em Markdown junto com uma saída navegável
- Graças à leve sintaxe Markdown e à busca integrada, autores podem se concentrar mais no conteúdo do que na formatação
- Blocos de código com realce de sintaxe e arquivos de tema permitem ajustar a legibilidade e o formato de saída necessários para documentação técnica
- Pré-processadores e backends oferecem pontos de extensão para sintaxe personalizada, modificação de conteúdo e renderização em vários formatos de saída
- Como é uma ferramenta usada em projetos Rust e no livro The Rust Programming Language, tem forte conexão com o ecossistema de documentação Rust
Recursos básicos para criar livros em Markdown
- mdBook é uma ferramenta de linha de comando para criar livros com Markdown
- É adequada para produzir conteúdos limpos e fáceis de navegar, como documentação de produtos, documentação de APIs, tutoriais e materiais de aula
- Oferece recursos que ajudam tanto na experiência de escrita quanto na de leitura
- Permite focar na criação de conteúdo com a sintaxe leve do Markdown
- Suporte a busca integrada dentro do livro
- Aplica realce de sintaxe colorido a blocos de código em várias linguagens
- Permite customizar o formato de saída com arquivos de tema
Extensões e conexão com o ecossistema Rust
- Pré-processadores podem cuidar da extensão de sintaxe personalizada e da modificação de conteúdo
- Por meio de backends, é possível renderizar em vários formatos de saída
- O mdBook é escrito em Rust para oferecer velocidade, segurança e simplicidade
- Dá suporte a testes automáticos de exemplos de código Rust
Casos reais de uso e formas de contribuição
- A própria documentação do mdBook é um exemplo de resultado gerado com mdBook
- O projeto da linguagem de programação Rust usa o mdBook, e o livro The Rust Programming Language também é um caso de uso
- O mdBook é um projeto gratuito e open source
- O código-fonte pode ser consultado no GitHub
- Issues e solicitações de recursos podem ser registradas no GitHub issue tracker
- Para contribuir, é possível ler o guia CONTRIBUTING e abrir um pull request
- O código-fonte e a documentação do mdBook são distribuídos sob a Mozilla Public License v2.0
1 comentários
Opiniões do Hacker News
Pelo que me lembro, esta plataforma usa bibliotecas hospedadas em CDN em vez de fazer bundle ou vendoring das bibliotecas. Com isso, o usuário fica exposto não só a falhas da CDN, mas também aos dados coletados por esse servidor
O que é ainda mais lamentável é que a forma como Highlight.js e MathJax são usados no front-end é muito desperdiçadora. Todos os clientes precisam analisar e renderizar a sintaxe e o LaTeX diretamente, e repetem o mesmo trabalho a cada visita para obter o mesmo resultado. O realce de sintaxe poderia ser processado em tempo de build, e quase não há motivo para precisar de JavaScript
Parece que essa escolha foi feita porque o suporte a MathJax é opcional: https://rust-lang.github.io/mdBook/format/mathjax.html
Ainda assim, é bem provável que o JS do MathJax carregue arquivos adicionais da CDN, então é difícil entender por que não deixar todos os arquivos do MathJax junto ao HTML gerado
As ferramentas de documentação e sites estáticos mencionadas nesta thread incluem mais ou menos Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit e JupyterBook
Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook
É um port do mdBook para Nim, mas também foi estendido com recursos para gerar conteúdo interativo usando o backend JavaScript do Nim. Não cheguei a usar pessoalmente, mas gosto da ideia de poder criar elementos interativos em um só lugar quando necessário: https://pietroppeter.github.io/nimib/interactivity.html
Já usei MdBook, Jekyll e MkDocs, e o MdBook é polido para projetos básicos, mas pareceu minimalista demais. Ao olhar o código-fonte de sites em MdBook de que gostei, havia casos em que eles tinham sido estendidos com código Rust customizado
Minha recomendação é: MkDocs como uma escolha padrão razoavelmente flexível; Jekyll quando é preciso mais flexibilidade, como em landing pages ou blogs; e Antora quando você quer criar o melhor site de documentação reunindo docs de vários projetos e várias versões, e está disposto a investir bastante esforço. O AsciiDoc tem muitos recursos úteis para escrever documentação
O Hugo parece flexível como o Jekyll, mas exige mais esforço para deixá-lo do jeito desejado, e os temas parecem variar demais no modo como funcionam. O tema que eu usava não tinha os recursos necessários, então tentei trocar por outro, mas a migração não foi fácil e acabei desistindo. O MdBook parece bem ativo, então acho que uma hora vai alcançar os outros
Adiei por muito tempo porque não queria usar ferramentas baseadas em JavaScript, mas, ao testar, vi que é fácil de começar, muito rápido, o site padrão é bonito e a customização também é simples. O suporte a MDX também é ótimo
Também estou testando o BookStack; ele é mais próximo de uma wiki, mas é bom para pessoas menos familiarizadas com tecnologia. Normalmente edito projetos MkDocs no VSCode e os mantenho em um repositório Git, mas o BookStack é totalmente baseado na web
Antigamente eu gerava o til.secretGeek.net com GitBook, mas ele foi ficando mais lento com o tempo, até o build do site levar 45 minutos, e os recursos que eu usava foram descontinuados ou viraram “premium”. No fim, foi o começo da enshittification
Se você está usando uma ferramenta gratuita que parece boa demais, é bem provável que ela se deteriore depois de alguns anos. No fim, criei eu mesmo um gerador de sites estáticos extremamente minimalista em .NET e voltei a fazer builds em poucos segundos. Não saio promovendo para os outros usarem, porque, se ele ficasse popular, acho que eu também acabaria estragando do mesmo jeito
https://www.collinsdictionary.com/jp/dictionary/english/spru...
Usei mdBook em vários projetos, mas hoje sinto que o material for mkdocs é mais agradável porque traz muito mais recursos prontos
Por exemplo, gosto do índice da página à direita, e esse recurso faz falta de forma evidente no mdBook. No mdBook, o padrão parece ser organizar o SUMMARY com bastante detalhe e dividir em vários arquivos conteúdos que originalmente poderiam ficar em uma única página
Comecei a usar mdBook há alguns dias para documentar um projeto pequeno, e ele é exatamente o pequeno gerador de páginas estáticas de que eu precisava
Também testei HUGO, mas, comparado ao mdBook, ele parece grande e pesado demais. Agora edito a documentação no Obsidian/VIM, faço push para o Gitea e, em menos de 1 minuto, a documentação pública é gerada
Com shortcodes adequados, dá para numerar automaticamente figuras, fórmulas etc. Fico curioso se o mdBook também permite numeração automática. Ele também tem índice à direita, tags e recurso para dividir páginas em colunas, além de bom suporte a KaTeX. O mdBook parece usar MathJax, e o deploy é fácil só com push ou rsync
Recentemente comecei a mover aos poucos alguns conteúdos de .md para .mdx e a explorá-los, e achei bem revigorante. O ponto mais difícil do Markdown para mim sempre foi que cada dialeto tem limitações diferentes, e cada um estende essas limitações de um jeito próprio
Estou muito satisfeito com 80–90% do dialeto padrão do GitBook Markdown, mas às vezes preciso de tabelas complexas, blocos de código que mantêm realce de sintaxe enquanto destacam só algumas linhas, sliders interativos, calculadoras embutidas na documentação ou gráficos/diagramas específicos. Não sei como MDX funcionaria em uma equipe grande, mas para trabalho individual parece uma melhoria clara
Seria ótimo se os dialetos desaparecessem e surgisse uma abordagem universal, mas a documentação diz que “MDX não está preso ao React e pode ser usado também com Preact, Vue, Emotion, Theme UI etc., além de dar suporte tanto ao runtime JSX classic quanto ao automatic”. Como já existe uma implementação para Svelte [1], não tenho certeza se desta vez não estamos abrindo uma caixa de Pandora com ainda mais dialetos presos a frameworks de front-end. Pode haver fragmentação dentro do próprio .mdx e também incompatibilidade com .md
[0] https://mdxjs.com/docs/what-is-mdx/
[1] https://mdsvex.com/docs
Há temas disponíveis, mas, se você for um desenvolvedor web moderno, criar o seu próprio também deve ser bem fácil
Criei uma ferramenta gratuita, open source e multiplataforma para produzir livros baseados em Markdown chamada KeenWrite: https://github.com/DaveJarvis/keenwrite
O KeenWrite chama o ConTeXt para a composição tipográfica do documento e, no modo de pré-visualização, usa um fork do KeenType para a composição de fórmulas. É possível gerar PDFs pela linha de comando. O livro em que estou trabalhando referencia no corpo do texto várias variáveis definidas em arquivos externos, passa propriedades do PDF por metadados e permite compilar apenas alguns capítulos pelo argumento chapters. O diretório theme contém instruções de composição tipográfica, como cores, fontes, layout e anotações
Exemplo de saída: https://github.com/DaveJarvis/keenwrite-themes/tree/main/exa...
Fico me perguntando por que Markdown, ou algum formato parecido, não é o formato padrão para livros, documentos e praticamente qualquer texto. Depois que migrei para o Typora alguns anos atrás, quase não preciso mais de Word/Writer para os textos que eu mesmo escrevo; acabo usando só para abrir documentos que outras pessoas me enviam
Também não vejo uma razão clara para que 90% dos livros que leio não estejam em formato Markdown. Entendo que, para imprimir livros físicos com boa aparência, é necessário fazer composição tipográfica, mas a maioria dos textos lidos em computadores ou smartphones, ou impressos diretamente a partir do MS/LibreOffice, de todo modo não passa por esse tipo de composição de forma adequada
Existem alternativas melhores, como AsciiDoc, mas elas são mais voltadas para documentação e não têm nem de perto o mesmo impulso do Markdown. Considerando que Markdown é um formato relativamente recente, a pergunta mais adequada talvez seja por que livros deveriam estar em Markdown. Em comparação com formatos binários ou baseados em XML, a maior vantagem do Markdown é ser texto puro e legível até certo ponto, mas isso não é tão importante para a maioria das editoras e leitores
Isso também é a armadilha clássica do engenheiro que pensa “eu consigo fazer melhor”, então não se deve partir dessa suposição sem pesquisar. Composição tipográfica é uma área muito mais antiga do que as ferramentas discutidas aqui, e não deveríamos descartar os insights e técnicas valiosos acumulados ao longo desse tempo só porque Markdown é quase suficiente para alguns usos
mdBook é fácil de usar, e gosto especialmente do fato de os usuários poderem escolher o tema. Uso principalmente para versões online de e-books [0] e para materiais que fiz curadoria [1][2]
[0] https://github.com/learnbyexample/scripting_course#ebooks
[1] https://learnbyexample.github.io/py_resources/
[2] https://learnbyexample.github.io/curated_resources/