50 lines
2.7 KiB
Markdown
50 lines
2.7 KiB
Markdown
# US09-01 — Serve the Documentation Inside the Application
|
|
|
|
Epic: [E09](../E09-documentation.md)
|
|
|
|
As an operator who was handed a URL and an access secret, I want the manuals inside the
|
|
application I am looking at, so that understanding it does not require a repository
|
|
checkout or an internet connection.
|
|
|
|
## Acceptance criteria
|
|
|
|
- Documentation lives as markdown under `docs/`, with an index that names every page and
|
|
the order it is meant to be read in. The same files render on Gitea without
|
|
modification.
|
|
- The application serves a `/docs` view reachable from the main navigation, listing the
|
|
pages and rendering the selected one.
|
|
- Rendering uses a vendored, version-pinned markdown library committed under
|
|
`frontend/js/vendor/`. It is not fetched from a CDN, not bundled by a build step, and
|
|
not written by hand. The build records the version and a checksum of the vendored file.
|
|
- Diagrams written as ```mermaid``` fenced blocks render as diagrams. Mermaid is vendored
|
|
the same way.
|
|
- `script-src` in the Content-Security-Policy is unchanged: no `'unsafe-eval'`, no
|
|
`'unsafe-inline'`. Only `style-src` gains `'unsafe-inline'`, and the reason is recorded
|
|
where the policy is defined.
|
|
- Links between documents work in the app: a relative `../foo.md#section` link navigates
|
|
to that page and heading rather than downloading a file or leaving the application.
|
|
Every heading has a stable anchor, and a deep link to an anchor scrolls to it.
|
|
- An unknown page renders a documentation-specific not-found message with a link back to
|
|
the index, and never exposes a filesystem path.
|
|
- Documentation is readable without an access secret **or** behind the same session as
|
|
the rest of the application — whichever is chosen is stated explicitly in the story's
|
|
implementation notes and covered by a test, because an operator locked out by a
|
|
configuration mistake is exactly who needs the troubleshooting page.
|
|
- The view works with no outbound network access at all.
|
|
|
|
## Automated tests
|
|
|
|
- Unit: heading-anchor slugs (duplicates, punctuation, non-ASCII), and the rewriting of
|
|
relative markdown links into in-app routes.
|
|
- Integration: every markdown file under `docs/` is reachable from the index; every
|
|
internal link in every document resolves to a file and, where an anchor is given, to a
|
|
heading that exists; the vendored library files match their recorded checksums.
|
|
- Browser: the documentation view renders a page, follows an internal link, deep-links to
|
|
an anchor, renders a mermaid diagram to an SVG, and shows the not-found message for an
|
|
unknown page — all with **zero console errors and zero CSP violations**, asserted, not
|
|
eyeballed.
|
|
|
|
## Dependencies
|
|
|
|
- None beyond the delivered application.
|