Skip to content

Add an automatically published web reader for the Typst paper #1144

Description

@isPANN

Motivation

The research paper is maintained in docs/paper/reductions.typ, and the documentation workflow already compiles it to book/reductions.pdf. The public website currently links directly to that PDF, so readers leave the site navigation and get a browser-dependent raw PDF view.

The paper should be readable from a first-party website page without introducing a second manually maintained document. The Typst source must remain the canonical source, and readers must retain a direct PDF download.

Typst native HTML export is not a suitable production dependency yet. Typst 0.15 marks HTML export as under active development and incomplete, while the deployment workflow currently pins Typst 0.14. The stable implementation should therefore reuse the PDF that the project already builds.

Objective

Add a website paper reader that is generated and published automatically from the existing Typst build:

docs/paper/reductions.typ
        -> typst compile
book/reductions.pdf
        -> embedded by
book/paper.html

docs/paper/reductions.typ remains in the repository and remains the only paper source. No generated paper copy is maintained by hand.

Recommended implementation

Use the existing mdBook pipeline instead of adding a new frontend or document converter:

  1. Add a docs/src/paper.md page and include it in docs/src/SUMMARY.md.
  2. Embed reductions.pdf with a native <object type="application/pdf"> or equivalent accessible browser element.
  3. Put a normal Download PDF link outside the embed and repeat it as the fallback content inside the embed.
  4. Give the embedded document an accessible title and make the reader fill the available viewport without causing horizontal page overflow.
  5. Change website links whose intent is reading the paper to open paper.html; keep explicit download links pointed directly at reductions.pdf.
  6. Continue compiling the PDF from docs/paper/reductions.typ in the documentation workflow. A Typst compilation failure must fail the deployment.

This requires no PDF viewer dependency. If native embedding proves insufficient on supported browsers, evaluate a self-hosted PDF.js viewer separately rather than loading a third-party hosted viewer.

Acceptance criteria

  • docs/paper/reductions.typ and its Typst build remain intact and are not replaced by generated HTML or Markdown.
  • The deployed site exposes a stable /paper.html reader page.
  • The reader displays the automatically compiled /reductions.pdf on browsers with native PDF embedding.
  • A visible Download PDF link points directly to /reductions.pdf.
  • Browsers that cannot embed PDFs receive a clear fallback link instead of an empty frame.
  • Homepage, footer, documentation, and generated detail-page reading links consistently open the reader page; download links remain direct.
  • Generated PDF or HTML output is not committed to the repository.
  • The website browser check verifies that the reader page, PDF embed target, and download link exist.
  • The GitHub Pages workflow builds the paper and publishes both paper.html and reductions.pdf from the same revision.

Out of scope

  • Deleting or converting away from the Typst source.
  • Maintaining a second hand-written paper in Markdown or HTML.
  • Depending on experimental Typst HTML output for production deployment.
  • Adding a custom PDF rendering frontend before native embedding is shown to be insufficient.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions