DocsWhy AscribeGitHub

Bring existing docs to Ascribe

Start a project in a folder of Markdown you already have, and take it from ascribe init to a clean ascribe check.

For AI agents: the documentation index is at llms.txt, and this page is available as Markdown.

Ascribe reads plain CommonMark, so a folder of Markdown is most of a project already. This guide starts a project around one, fixes what the first check finds, and shows what to rewrite in pages written for another tool: links, frontmatter, callouts, and heading ids.

The pages here are examples/existing-docs: four pages in docs/, some with frontmatter and some without, and one link written as the address the old site published.

Before you start

  • Install the command, as Getting started does.
  • Commit the pages first, so that git diff shows each change Ascribe makes.

Start the project

In the folder that holds docs/:

npx ascribe init

When the pages are in another folder, name it, from the folder you run init in: npx ascribe init --content-root guides. It’s the folder the pages are in, not the project’s own, so the build’s output stays out of it.

init writes ascribe.toml, counts the pages it found, and checks them:

ascribe 0.4.4 on Linux
wrote ascribe.toml
wrote ascribe.addresses, where a page's move is recorded, so the addresses it published keep working
found 4 pages in docs/; with no page types declared in ascribe.toml, no page needs `type:`
3 pages have no `title`; `ascribe check --fix` takes the opening heading as the title of 2 of them, and the rest need `title:` written in their frontmatter
`ascribe check` finds 4 errors, 0 warnings, 5 advice:
  3  ASC048 frontmatter-missing-field (error)
  3  ASC150 page-description-missing (advice)
  2  ASC151 heading-level-skipped (advice)
  1  ASC036 link-target-missing (error)
Next, run `ascribe check --fix`, which fixes 2 of them, then `ascribe check --code ASC048`
To put the advice off, so the check reports only what's new: `ascribe baseline write`
Then, to publish the pages as a site with Astro, read https://ascribed-dev.com/go/astro-guide/

The ascribe.toml it writes for a folder of pages declares no page types. Every page is then of the one implicit type, page, and none of them has to say type: in its frontmatter. Each needs a title, and can have a description:

ascribe 0.4.4 on Linux
# The project's content model: where its pages are, and what each kind of
# page must say in its frontmatter. `ascribe check` and the editor read it.
# Every section is in the reference: https://ascribed-dev.com/go/content-model/
spec = "0.1"

[project]
# The folder the pages are in. A link that starts with `/` starts here.
content-root = "docs"

# What most projects add next:
#
# - A phrase, such as the product's name, written once here and on a page as
#   {product}: https://ascribed-dev.com/go/phrases/
# - A dimension, such as the reader's platform, for content that's for some
#   readers only: https://ascribed-dev.com/go/dimensions/
# - [consumer], the site the pages are published as, and its address:
#   https://ascribed-dev.com/go/consumer/

# No page types: every page is of the one implicit kind, `page`, and names
# no type in its frontmatter. Each needs a `title`, and can have a
# `description`. Once a type is declared here, each page names its own, as
# `type: page`: https://ascribed-dev.com/go/content-model/
[frontmatter]
description = "string?"

In an empty folder, init declares the type page instead, which each page names; ascribe init has both. --templates, which declares six types, is refused in a folder of pages, since each page would have to name one. Take the templates once the pages check clean, with ascribe templates eject, then give each page type:, since the project declares types from then on.

Fix what the check finds

  1. Apply the safe fixes:

    npx ascribe check --fix

    A page with no title that opens with a level-1 heading takes the heading as its title: the fix writes it in the frontmatter, and takes the heading out of the page, since the site shows the title in its place. A link written as a page’s published address, such as /guides/alerts/, is rewritten to the page’s file. What’s left is listed:

    ascribe 0.4.4 on Linux
    fixed 1 problem in docs/guides/alerts.md
fixed 1 problem in docs/index.md
docs/guides/alerts.md:13: [ASC036] `../install.html` doesn't exist
docs/guides/troubleshooting.md:1: [ASC048] the required field `title` is missing; the content type `page` needs it
docs/guides/alerts.md:1: [ASC150] this page has no `description`; write a sentence saying what the page is for, which search results and agents show with its title
docs/guides/troubleshooting.md:1: [ASC150] this page has no `description`; write a sentence saying what the page is for, which search results and agents show with its title
docs/index.md:1: [ASC150] this page has no `description`; write a sentence saying what the page is for, which search results and agents show with its title
checked 4 files for every build, 3 with problems: 2 errors, 0 warnings, 3 advice

    A fix is safe only when it can’t change what the page says. A page whose opening heading something links to, as #configure-alerts, isn’t given the heading as its title by --fix, since the link would lose its target; the fix is offered in the editor, for you to apply and fix the link.

  2. Give the other pages a title. troubleshooting.md opens with a paragraph, so it gets frontmatter:

    ---
title: When a page doesn't load
---

  3. Fix the links. A link in Ascribe names the file it goes to, and each output writes its address, so [Install Lantern](../install.html) becomes [Install Lantern](../install.md). ascribe check --code link-target-missing lists every link that names no file.

  4. Put the advice off. Advice never fails the check: here it’s the pages with no description. To deal with it later, and have the check report only what’s new, record it in ascribe.baseline:

    npx ascribe baseline write
    ascribe 0.4.4 on Linux
    wrote ascribe.baseline: 3 problems in 3 files, 3 added; commit it with the docs

    See The baseline for what it holds back, and how it shrinks as you fix each.

  5. Check again:

    npx ascribe check
    ascribe 0.4.4 on Linux
    checked 4 files for every build, 0 with problems: 0 errors, 0 warnings, 0 advice, 3 in the baseline

Commit ascribe.toml, ascribe.baseline, and the pages, and add .ascribe/ to .gitignore. To check every pull request, see Check in CI.

What to rewrite in pages from another tool

The check finds the links and the frontmatter that need a change. It doesn’t find callouts or heading ids written in another tool’s syntax: they’re text to Ascribe, so the site shows them as they’re written. Search for them:

grep -rnE '^(:::|!!! |> \[!)|\{#[^}]*\}\s*$|\[\[' docs/
Written as In Ascribe
[Install](install.html), [Install](/install/) [Install](install.md): the file. A published address is reported, and --fix rewrites it; an .html link is reported as missing, for you to rewrite.
[[Install]], [[install|Install it]] [Install it](install.md)
:::note … :::, !!! note, > [!NOTE] @note, as @note: One line., or @note {type=warning}: … @end around several blocks
## Setup {#setup} ## Setup, with @id: setup on the line below it (@id)
A frontmatter key for the sidebar’s label nav-label, which every page can have
A frontmatter key for the page’s place in the sidebar ascribe.nav, which orders the pages and sections
Any other frontmatter key A field in [frontmatter] in ascribe.toml, such as tags = "list(string)?", or nothing: a key ascribe.toml doesn’t declare is reported

The callout types are note, tip, important, warning, and caution; [notes] in ascribe.toml declares others. Only .md files are pages: rename a .mdx file whose components you’ve replaced, and keep a file that isn’t a page out of the content root, or in a folder whose name starts with ..

See also