> For the complete documentation index, see [llms.txt](https://ascribed-dev.com/docs/llms.txt). This documentation describes Ascribe 0.4.4. Anything marked in main, not yet released isn't in that release yet. # Bring existing docs to Ascribe > How-to · Start a project in a folder of Markdown you already have, and take it from ascribe init to a clean ascribe check. 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`](https://github.com/ascribed-dev/ascribe/tree/main/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](https://ascribed-dev.com/docs/getting-started.md#install-the-command) does. - Commit the pages first, so that `git diff` shows each change Ascribe makes. ## Start the project In the folder that holds `docs/`: ```sh 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: ```text 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/ ``` Tested with ascribe 0.4.4 on Linux. 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`: ```toml # 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?" ``` Tested with ascribe 0.4.4 on Linux. In an empty folder, `init` declares the type `page` instead, which each page names; [`ascribe init`](https://ascribed-dev.com/docs/install.md#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`](https://ascribed-dev.com/docs/templates/command.md#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: ```sh 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: ```text 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 ``` Tested with ascribe 0.4.4 on Linux. 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: ```markdown --- 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`: ```sh npx ascribe baseline write ``` ```text wrote ascribe.baseline: 3 problems in 3 files, 3 added; commit it with the docs ``` Tested with ascribe 0.4.4 on Linux. See [The baseline](https://ascribed-dev.com/docs/checks/baseline.md) for what it holds back, and how it shrinks as you fix each. 5. Check again: ```sh npx ascribe check ``` ```text checked 4 files for every build, 0 with problems: 0 errors, 0 warnings, 0 advice, 3 in the baseline ``` Tested with ascribe 0.4.4 on Linux. Commit `ascribe.toml`, `ascribe.baseline`, and the pages, and add `.ascribe/` to `.gitignore`. To check every pull request, see [Check in CI](https://ascribed-dev.com/docs/checks/ci.md). ## 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: ```sh 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`](https://ascribed-dev.com/docs/writing/directives.md#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`](https://ascribed-dev.com/docs/writing/directives.md#id)) | | A frontmatter key for the sidebar's label | `nav-label`, which [every page can have](https://ascribed-dev.com/docs/writing/frontmatter.md#reserved-keys) | | A frontmatter key for the page's place in the sidebar | [`ascribe.nav`](https://ascribed-dev.com/docs/navigation/order.md), 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 - [`ascribe init`](https://ascribed-dev.com/docs/install.md#ascribe-init): what it writes, and its options. - [`ascribe check`](https://ascribed-dev.com/docs/checks/check.md): the check, its formats, and `--fix`. - [Frontmatter](https://ascribed-dev.com/docs/writing/frontmatter.md): the keys every page can have. - [The `ascribe.toml` reference](https://ascribed-dev.com/docs/content-model.md): types, and the fields they share.