Publish a Portable Documentation Site

Publishing a site has three steps:

1. Load a collection and verify its source artifacts.
2. Use a site source to choose routes, visibility, and navigation.
3. Render the validated site.

This notebook follows those steps with a small HTML renderer. A production renderer can live in another package and implement the same behaviour.

This example covers the existing core export path. The coordinated completion checklist tracks renderer adoption of presentation settings, hosted API pairing and complete artifact preview/reader qualification. They are not options exercised by this notebook. The host supplies source policy and brand content; renderer packages own the visual controls and preview, while native readers and producer algorithms stay with their respective consumers/producers. The settings section below describes the settings contract included in the pinned 2.0.0 package.

Setup

Run the notebook from Livebook's default standalone runtime. The release task keeps this exact package version in sync with mix.exs.

Mix.install([
  {:doc_shell, "== 2.0.0"}
])

Application.ensure_all_started(:doc_shell)

Define host policy

The source below selects one qualified document and gives it a stable route. It does not read files or render HTML; loaded collections are its only input.

defmodule SitePublication.Source do
  @behaviour DocShell.Presentation.SiteSource

  @impl true
  def project(_collections, _options) do
    {:ok,
     %{
       "title" => "Example documentation",
       "base_path" => "/docs/",
       "default_locale" => "en",
       "locales" => ["en"],
       "pages" => [
         %{"id" => "example:intro", "route" => "/start/"}
       ],
       "navigation" => [
         %{
           "id" => "guides",
           "title" => "Guides",
           "children" => [%{"id" => "example:intro"}]
         }
       ],
       "redirects" => %{"/old/" => "/start/"},
       "metadata" => %{"owner" => "documentation"}
     }}
  end
end

The map declares the host's site policy. A database or graph projection can produce it too; the returned values must remain inert JSON. In the current checkout, automatic reading links stay within the same locale, audience set and nearest navigation group. Explicit previous/next document IDs can cross sections or apply to a page omitted from navigation. Badges use nonempty text (up to 256 UTF-8 bytes), and collapsed is a boolean on a navigation group.

Presentation settings in DocShell 2.0.0

The source may also return a presentation object. For example:

{
  "brand": {"label": "Example", "href": "/docs/start/"},
  "labels": {"search": "Search examples"},
  "locales": [{"id": "en", "label": "English", "href": "/docs/start/", "current": true}],
  "footer": {"text": "Example documentation", "links": []},
  "metadata": {"description": "Example documentation", "robots": ["index", "follow"]},
  "robots": {"allow": ["/docs/"]}
}

DocShell.Presentation.Settings.validate/1 checks this inert data before projection. The exporter forwards it as context.presentation for both pages and not-found output, and uses the explicit robots.txt rules. A renderer implements its own controls and recognizes its own label keys; the source supplies translations, destinations and brand content. The runnable baseline below uses no settings, so it also works with the pinned release.

Page decoration data in DocShell 2.0.0

Page declarations may carry banner records (label, text, href) and hero records (title, tagline, description, ordinary link actions, and an image logical asset/alt record). PageDecorations.validate/2 checks them. Use metadata["seo"] for page description/image/robots overrides. All values stay inert and must be JSON-encodable. The complete projected page, including metadata and reading relationships, must fit its byte budget. These fields do not choose a host's product layout or supply executable rendering callbacks.

Hosted API pairing in DocShell 2.0.0

A graph-backed host can call DocShell.Presentation.HostedPair.validate(presentation, openapi, expected) before invoking a renderer. Put the same doc-shell-publication/v1 binding in the presentation's :publication field, OpenAPI's x-doc-shell-publication extension, and the host's expected request view. The required opaque fields are publication_id, source_view, graph_position, locale, release, and disclosure_surface. Missing or mismatched fields refuse, including stale inputs that agree with each other but differ from the expected publication. This API is included in DocShell 2.0.0. Host authorization and source authenticity remain prerequisites; a matching declaration grants no access.

Define a small renderer

The renderer declares what it can provide, returns logical assets, and renders already validated pages. It does not choose routes or write the destination.

defmodule SitePublication.Renderer do
  @behaviour DocShell.Presentation.Renderer

  alias DocShell.Presentation.{Asset, Page, Site}
  alias DocShell.Presentation.Renderer.{Capabilities, Capability, Context}

  @impl true
  def capabilities do
    %Capabilities{
      schema_version: Capabilities.schema_version(),
      renderer_id: "site-publication-example",
      renderer_version: "1.0.0",
      output_modes: [:static],
      features: %{
        "doc-shell/html/v1" => %Capability{states: [:fallback], runtime: []}
      }
    }
  end

  @impl true
  def assets(%Site{}, []) do
    {:ok,
     [
       %Asset{
         path: "site.css",
         media_type: "text/css",
         bytes: "main{max-width:48rem;margin:4rem auto;font:18px system-ui}"
       }
     ]}
  end

  @impl true
  def render_page(%Page{} = page, %Context{} = context) do
    body = Enum.map(page.content, &render_node/1)
    css = Map.fetch!(context.assets, "site.css")

    {:ok,
     [
       "<!doctype html><html lang=\"",
       escape(page.locale),
       "\"><head><meta charset=\"utf-8\"><title>",
       escape(page.title),
       "</title><link rel=\"stylesheet\" href=\"",
       escape(css),
       "\"></head><body><main id=\"main\">",
       body,
       "</main></body></html>"
     ]}
  end

  @impl true
  def render_not_found(%Site{}, %Context{}) do
    {:ok, "<!doctype html><html><body><main>Not found</main></body></html>"}
  end

  defp render_node(text) when is_binary(text), do: escape(text)

  defp render_node(%{"tag" => tag, "attrs" => attrs, "content" => content})
       when tag in ["h1", "p", "strong", "em"] do
    id = if tag == "h1", do: [" id=\"", escape(Map.get(attrs, "id", "")), "\""], else: []
    ["<", tag, id, ">", Enum.map(content, &render_node/1), "</", tag, ">"]
  end

  defp render_node(%{"content" => content}), do: Enum.map(content, &render_node/1)

  defp escape(value) do
    value
    |> to_string()
    |> String.replace("&", "&amp;")
    |> String.replace("<", "&lt;")
    |> String.replace("\"", "&quot;")
  end
end

Unknown AST elements above keep their safe child content. Production HTML renderers should use a complete allowlist and validate link schemes as described by the renderer contract.

Build and load a collection

The source revision and tree digest come from the caller. DocShell records them; it does not run Git or authenticate a checkout.

workspace =
  Path.join(
    System.tmp_dir!(),
    "doc_shell_site_publication_#{System.unique_integer([:positive])}"
  )

File.rm_rf!(workspace)
File.mkdir_p!(Path.join(workspace, "guides"))

File.write!(Path.join(workspace, "guides/intro.md"), """
---
id: intro
title: Introduction
---

# Introduction

This page came from a validated portable collection.
""")

artifact_dir = Path.join(workspace, "artifacts")

{:ok, descriptor} =
  DocShell.Generate.Collection.new(%{
    id: "example",
    title: "Example",
    version: "1.0.0",
    revision: String.duplicate("a", 40),
    tree_digest: "sha256:" <> String.duplicate("b", 64),
    artifact_dir: artifact_dir,
    source_url: "https://example.invalid/example",
    edit_base_url: "https://example.invalid/example/edit"
  })

{:ok, _result} =
  File.cd!(workspace, fn ->
    DocShell.Build.run(
      modules: [],
      guide_bases: ["guides"],
      livebook_base: "notebooks",
      changelog_source: false,
      public_dir: artifact_dir,
      private_dir: Path.join(workspace, "private"),
      collection: descriptor
    )
  end)

{:ok, collection} = DocShell.Generate.Collection.load(descriptor)

Enum.map(collection.documents, & &1["id"])

Project the site

Projection resolves anchors, links, breadcrumbs, reading order, search records, visibility, and capability requirements before a renderer sees the page.

{:ok, site} =
  DocShell.Presentation.SiteProjector.project(
    collections: [collection],
    source: SitePublication.Source,
    profile: "public",
    generation_id: "site-publication-example",
    canonical_origin: "https://docs.example"
  )

page = site.pages["example:intro"]

%{
  schema: site.schema_version,
  route: page.route,
  headings: Enum.map(page.headings, & &1.id),
  breadcrumbs: Enum.map(page.breadcrumbs, &{&1.title, &1.path}),
  requirements: Enum.map(page.requirements, & &1.feature_id)
}

The cohort digest is deterministic for the same collections and profile. The generation ID identifies this publication attempt and may differ on a rebuild.

Export the static tree

The exporter validates renderer capabilities and output, hashes local assets, checks links and limits, stages the whole tree, and then replaces the destination.

destination = Path.join(workspace, "site")

{:ok, manifest} =
  DocShell.Presentation.StaticExporter.export(
    site: site,
    renderer: SitePublication.Renderer,
    destination: destination,
    canonical_origin: "https://docs.example"
  )

%{
  renderer: manifest["renderer"],
  routes: manifest["routes"],
  files: destination |> Path.join("**/*") |> Path.wildcard() |> Enum.map(&Path.relative_to(&1, destination))
}

site-manifest.json records every generated payload except itself, avoiding a self-referential digest. The tree also contains 404.html, search data, sitemap.xml, robots.txt, llms.txt, and llms-full.txt.

Query the same search corpus

The built-in adapter is both the default static index and a reference query implementation. Other adapters consume the same records.

{:ok, matches} =
  DocShell.Presentation.SearchAdapter.JSON.query(site.search, "validated", locale: "en")

Enum.map(matches, &{&1.id, &1.route})

External artifact blocks (experimental)

External illustrations and other typed artifact blocks have an experimental static implementation.

This notebook continues to exercise the unchanged v1 path. The executable artifact tests separately exercise verified fallback, unknown optional profiles, per-state runtime selection and the same static exporter.

Runtime requirement ordering does not change selection. Script-free export rejects browser JavaScript MIME aliases, case variants and MIME parameters before publication. Empty sites still validate their artifact options.

A host passes :artifact_options explicitly; it never starts an artifact producer implicitly. Independent Svelte/HEEx archive reader observations are recorded in the shared plan. Producer algorithms and native applications stay with their consumers.

Clean up

File.rm_rf!(workspace)
:ok

Artifact input budgets in DocShell 2.0.0

For artifact-bearing pages, pass positive :limits through :artifact_options. ArtifactLimits.new/1 supplies defaults for page/AST/JSON size and depth, block/binding/variant counts, descriptors, manifests, projections and assets. ArtifactBlock.project_many/2 validates every page before loading descriptors, then loads each descriptor once per invocation. Static export uses this batch path and applies the lower site page/depth ceilings. A late invalid page cannot invoke an earlier page's producer or replace the prior output. These APIs are available in DocShell 2.0.0; they do not relax source authentication, producer limits or renderer qualification.

The packaged priv/contracts/artifact-contracts-v1.schema.json contains structural definitions for nodes, descriptors, variants, capabilities, receipts and export manifests. artifact-conformance-v1.json contains frozen synthetic chart/drawing inputs, exact original bytes, expected selections and semantic observations. Tests use a separate schema engine only in development/test; DocShell core does not acquire that runtime dependency. These vectors do not establish external producer or native-reader conformance.

In file-reader mode, resolve selected asset URLs against presentation-manifest.json itself. HTML has page-relative URLs; the manifest has output-root-relative paths and lists only selected artifact assets. Web mode retains root-relative URLs.

Before displaying an existing artifact receipt, call ArtifactBlock.verify_receipt(content, receipt). It checks the portable binding without producer callbacks or a second presentation choice. The original producer admission and source authenticity remain host prerequisites. A static renderer receives selected original bytes in context.artifact_assets as %{"media_type" => type, "base64" => encoded_bytes} records, so it can check its own media subset and raw digest without fetching URLs or reading files.

Artifact binding targets must be textual AST attrs.id values. JSON arrays, objects, numbers and booleans cannot stand in for an anchor that readers ignore; a genuine textual target may be outside the artifact's fallback subtree. The void br element must have empty content; putting fallback text under it fails admission rather than disappearing in HTML output.