Editing these docs

This is a tutorial for the team maintaining the Xago Invoice documentation. It covers where the content lives, how to change it, and how to check your work before it ships.

Where the content lives

The site is built with Astro + Starlight. Every page in this section is one Markdown file in the repository:

src/content/docs/xago-invoice/
  index.mdx                      Product landing page
  getting-started/               Overview, installation, quick start
  guide/                         Day-to-day tasks, for end users
  administration/                Setup, access point, job queue
  reference/                     Glossary, FAQ, release notes — and this page

The URL mirrors the path: guide/sending-invoices.md becomes /xago-invoice/guide/sending-invoices/.

Edit an existing page

1. Open the page’s .md file and change the text. The body is plain Markdown: headings with ##, bold, lists, links, tables.
2. Leave the block between the --- lines at the top (the frontmatter) intact unless you mean to change it. title is the page heading and sidebar entry; description feeds search engines and link previews.
3. Preview and build (see below), then commit.

Add a new page

1. Create a .md file in the section directory it belongs to, with frontmatter at the top:

   ---
   title: My new page
   description: One sentence on what this page covers.
   sidebar:
     order: 4
   ---
   
   Body text starts here.

2. Set sidebar.order to position the page within its section — the sidebar sorts on this number, not on filenames. Check the neighbouring pages’ values and pick the right slot.

3. The sidebar picks the page up automatically; each section is autogenerated from its directory. No configuration change needed.

4. Link to it from related pages with a site-absolute path: [My new page](/xago-invoice/guide/my-new-page/) — note the trailing slash.

House rules

• Don’t guess product behaviour. Anything unverified is marked with a TODO aside naming what to confirm:

  :::note[TODO]
  Confirm the action name on the sales invoice page.
  :::

  Never replace one of these with an invented answer — the point is that it is unconfirmed. Resolve it by checking the product, then replace the aside with the verified text.

• Use .md, not .mdx, unless the page imports Starlight components such as <Card> or <LinkCard> (the landing page does). Component tags in a plain .md file render as literal text.

• Use tables, not definition lists — definition lists are not supported by the markdown pipeline. See the glossary for the pattern.

Preview your changes

From the repository root, start the dev server in background mode:

astro dev --background

Then open the URL it prints (typically http://localhost:4321) and navigate to your page. Pages hot-reload as you save. Manage the server with astro dev status, astro dev logs and astro dev stop.

Check before you’re done

npm run build

The build validates every page’s frontmatter against the content schema and fails on broken configuration. A content change is not done until the build passes.

Translations

English lives at the root and is the source of truth. Translations mirror the same path under a locale directory: translating this page to Norwegian means creating src/content/docs/no/xago-invoice/reference/editing-these-docs.md. Untranslated pages automatically fall back to English with a notice, so partial translation is fine.