#Documentation
25 posts
Build a Manual with Docusaurus #3: Writing Content — Code Blocks, Mermaid, Admonitions
We cover three elements that make docs easy to read: code blocks with titles and line highlighting, Mermaid diagrams drawn as code, and admonitions that surface cautions and warnings. Here's how to use each in Docusaurus.
Build a Manual with Hugo #4: Deploying to Cloudflare Pages and Connecting a Domain
We send the docs we built locally out into the world. We cover pushing to GitHub, connecting to Cloudflare Pages and setting up the build, and attaching a custom domain. We also point out Hextra's Go module and the publish-date trap along the way.
Build a Manual with MkDocs #3: Writing Content — Code Blocks, Mermaid, and Admonitions
We cover three elements that make docs pleasant to read: code blocks with titles and line highlighting, Mermaid diagrams drawn as code, and admonitions that make cautions and warnings stand out. Here's how to use them in MkDocs Material.
Build a Manual with Starlight #3: Writing Content — Code Blocks, Mermaid, asides
We cover three elements that make docs pleasant to read: code blocks that carry titles and line highlights, Mermaid diagrams added via a plugin, and asides that show cautions and warnings. We go over how to use each in Starlight.
Build a Manual with Docusaurus #2: Sidebar and Search — Structuring Your Documentation
When docs grow into dozens of pages, the sidebar and search are what keep readers from getting lost. We'll set up the sidebar in sidebars.js, both automatically and manually, and lay out your options for adding search in Docusaurus.
Build a Manual with Hugo #3: Writing Content — Code Blocks, Mermaid, Callouts
We cover three elements that make docs pleasant to read. From code blocks that carry filename and line highlighting, to Mermaid diagrams drawn as code, to callouts that make cautions and warnings stand out — we cover how to use each in Hextra.
Build a Manual with MkDocs #2: nav and Search — Shaping the Information Structure of Your Docs
Even as your docs grow to dozens of pages, a sidebar and search are what keep readers from getting lost. We'll design the nav directly in mkdocs.yml, turn on Material's navigation features, and enable the built-in search.
Build a Manual with Starlight #2: Sidebar and Search — Structuring Your Docs
When your docs grow to dozens of pages, the sidebar and search are key to keeping readers from getting lost. We configure the sidebar automatically and manually in Starlight, and take a look at the built-in search.
Build a Manual with Docusaurus #1: From Install to Your First Doc
Lay the foundation for a team docs or product manual site with Docusaurus. We'll go from setting up Node.js to creating a site with create-docusaurus and serving your first doc on the dev server, all in one pass.
Build a Manual with Hugo #2: Sidebar and Search — Shaping the Information Architecture
Even as your docs grow to dozens of pages, the sidebar and search are what keep readers from getting lost. We cover shaping the sidebar hierarchy from the folder structure in Hextra, ordering it with weight, and attaching the top menu and the built-in search.
Build a Manual with MkDocs #1: From Install to Your First Doc
Set up the skeleton of a team documentation or product manual site with MkDocs and the Material theme. We'll go all the way from installing into a Python virtual environment, to creating a new site, applying the theme, and serving your first doc on a local server.
Build a Manual with Starlight #1: From Install to Your First Doc
We set up the skeleton of a team documentation and product manual site with Astro's Starlight, walking through everything from getting Node.js ready to creating a site with create astro and bringing up your first doc on the dev server.