dev_docs

dev_docs packages the repository Markdown docs as a Pharos app. The app owns navigation, templates, CSS, and static assets. The docs/ tree owns the written content. Pharos owns the build and render pipeline that turns those inputs into the packaged site.

Run the app first

Build and serve the current app bundle:

pharos build app dev_docs --build-dir dist
pharos serve app dev_docs --build-dir dist --port 8081

Then open:

http://127.0.0.1:8081/dev_docs/

Keep that running while you read and change the app.

Open these files in order

Read the source in this order:

1. apps/dev_docs/pharos.app.yml
2. apps/dev_docs/nav.yml
3. apps/dev_docs/templates/docs-page.html
4. apps/dev_docs/templates/docs-sidebar.html
5. apps/dev_docs/templates/docs-sidebar-item.html
6. apps/dev_docs/templates/docs-index.html
7. apps/dev_docs/static/css/docs.css
8. docs/tutorials/README.md
9. docs/tutorials/dev_docs.md
10. docs/quickstart/todo-list.md
11. docs/quickstart/audio-store.md
12. docs/tutorials/ucal.md

That order keeps the app contract first, then navigation, then shell, then styling, then the Markdown content that gets rendered into the app.

Start with the manifest

apps/dev_docs/pharos.app.yml declares the app identity, base path, docs input tree, output mapping, and the app-owned template and asset surfaces that the docs renderer uses.

app_id: dev_docs
app_kind: app
name: Pharos Framework Developer Docs
runtime:
  host_profile: static-pages
  build_artifact_dir: apps/dev_docs
  base_path: /dev_docs
docs:
  nav_manifest: nav.yml
  page_template: templates/docs-page.html
  sidebar_template: templates/docs-sidebar.html
  sidebar_item_template: templates/docs-sidebar-item.html
  index_template: templates/docs-index.html
  source_dir: ../../docs
  output_dir: .

The key point in this file is the split between app-owned surfaces and doc content:

• apps/dev_docs/ owns navigation, templates, CSS, and assets
• docs/ owns the authored Markdown pages
• the build turns both into dist/apps/dev_docs/

Then read the navigation

apps/dev_docs/nav.yml controls the sidebar order and the tutorial grouping. The current tutorial page organization keeps each app together instead of splitting one app across repeated cross-cutting sections.

Read the tutorial entries and the order they appear in the navigation:

- group_id: tutorials
  label: "Tutorials"
  items:
      - path: quickstart/todo-list.html
        label: "Todo List App"
      - path: quickstart/audio-store.html
        label: "Beacon Beats Store"
      - path: tutorials/ucal.html
        label: "UCAL App"
      - path: tutorials/dev_docs.html
        label: "Authoring dev_docs"

When this file changes, the sidebar and tutorial order change with it on the next build.

Then read the shell

The shell is app-owned HTML under apps/dev_docs/templates/.

• docs-page.html wraps each rendered page
• docs-sidebar.html wraps the nav list
• docs-sidebar-item.html renders one nav entry
• docs-index.html controls the landing page shell

These templates define layout and navigation, not the Markdown body copy.

<main class="docs-layout">
<aside class="docs-sidebar card" aria-label="Documentation navigation">{html:sidebar}</aside>
<section class="docs-content">
<section class="banner">
<img src="{wordmark_src}" alt="Pharos Framework" class="wordmark">
<p class="backlink"><a href="{back_href}">← Back</a></p>
{html:body}
</section>
</section>
</main>

{html:body} is where the rendered Markdown page lands inside the shell.

Then read the content pages

The Markdown source for the app lives under docs/.

For the tutorial path, keep the current grouping intact:

• docs/quickstart/todo-list.md
• docs/quickstart/audio-store.md
• docs/tutorials/ucal.md
• docs/tutorials/dev_docs.md

Each app page should carry one uninterrupted path for that app:

• running it
• reading the source in order
• making one visual change
• making one contract or content change
• rebuilding and reviewing locally
• moving to the next app only after that path is complete

That is the main editing rule for dev_docs: keep one app packet together and let the reader finish it before moving to the next app.

One contract to keep in mind

dev_docs is easiest to edit when you keep one dependency chain in mind:

1. pharos.app.yml decides what the docs build consumes
2. nav.yml decides how the pages are grouped and reached
3. app-owned templates decide layout and page chrome
4. docs/ supplies the authored content
5. dist/apps/dev_docs/ becomes the packaged review surface
6. dist/apps/dev_docs/html/ carries the generated Rust API and source reference

Make your first changes

Open:

apps/dev_docs/static/css/docs.css

Change one visible style in the docs shell, for example a spacing or accent value used by the tutorial pages. Then rebuild and refresh:

pharos build app dev_docs --build-dir dist
pharos serve app dev_docs --build-dir dist --port 8081

Reload /dev_docs/ and confirm the shell changed without editing any runtime code.

Then make one content change.

Open:

docs/tutorials/dev_docs.md

Change a sentence, add one short note, or adjust the order of a small list. Then rebuild and refresh the same local app.

The change flows through the docs pipeline into the packaged artifact under:

dist/apps/dev_docs/
dist/apps/dev_docs/tutorials/dev_docs.html
dist/apps/dev_docs/html/src/tutorials/dev_docs.md

That keeps authored Markdown and generated output separate.

App and framework boundary

• app-owned: pharos.app.yml, nav.yml, templates, CSS, images, and the docs shell
• docs-owned: the Markdown pages under docs/
• framework-owned: the docs build, Markdown rendering, template substitution, output materialization, and serving path

Review path

Use the running docs app for review, not just the Markdown diff.

Check:

• the tutorial order in the sidebar
• page-to-page backlinks
• local rendering of any images or SVG diagrams
• whether each app page reads as one grouped path rather than a broken-up sequence

Next

• Tutorial
• Build a database-backed Todo List
• Build the Beacon Beats audio store
• Build a scheduling and workflow app