Document tooling

Publisle

Portable semantic document standard for technical articles, docs, interactive explainers and research papers, with citations and LaTeX, JATS and PDF export.

typescriptrustmarkdownlatexpdfjatsdocuments

Overview

Publisle is a portable semantic document standard for technical articles, docs, interactive explainers and research papers, with citations and LaTeX, JATS and PDF export.

Publisle wordmark with the tagline Portable semantic articles, compiled to static HTML, and the address publisle.xyz

Why I started

When I was developing my website for blogging, I wanted a standard schematic system for blogging with version control and to be able to represent the full blog as pure MD with support for customized elements for interactivity while being focused on providing a compiled result for lightweight browsing without much client overhead, and to be able to create a searchable database for content on the website. I struggled to find a solution that solves all the points needed, so I made my own to be focused around providing a standard for portability between frameworks and browser-based compilation with an addon to compile an article as a research paper with support for bibliography and standard research paper format templates out of the box.

Approach and decisions

The main decision is to keep a portable document model at the center, and compile out from that model instead of tying the article to one framework or one export format, That ensures portability without enforcing strict frameworks limits that can be expanded later easily.

A document can be wrttien with Markdown or typed JSON. The source is checked against the schema, then prepared and validated over Publisle documentation standard. The compiler turns the prepared document into a static reader page, and the same document can go through a framework host using provided adapters: Svelte, React, Next.js, Astro, or Vue. Interactive elements keep their authored fallbacks, so the compiled page stays readable without much client overhead.

As per design decision for flexibility of design most of the library infrastrcture is built as addons over the core library package for decoupled development, With prime example being @publisle/cli-research, the same document can pick up bibliography support, BibTeX and CSL, and export to LaTeX, PDF, and JATS, including standard research paper format templates. Core itself does not pull in TeX, citeproc, or those templates.

A source document in Markdown or typed JSON goes through the schema for the document model and validation, then Core prepare and validate. From Core it can go to the compiler for static HTML and framework hosts, to Markdown or GFM, or to the Research profile addon, which exports LaTeX and PDF, JATS XML, and CSL and BibTeX citations.A source document in Markdown or typed JSON goes through the schema for the document model and validation, then Core prepare and validate. From Core it can go to the compiler for static HTML and framework hosts, to Markdown or GFM, or to the Research profile addon, which exports LaTeX and PDF, JATS XML, and CSL and BibTeX citations.
Open full-size diagramOpen full-size diagram
Diagram source (mermaid)
flowchart TB
  src["Markdown or typed JSON"]
  schema["Schema: document model and validation"]
  core["Core: prepare and validate"]
  src --> schema --> core
  core --> web["Compiler: static HTML and framework hosts"]
  core --> mdout["Markdown / GFM"]
  core --> research["Research profile addon"]
  research --> latex["LaTeX and PDF"]
  research --> jats["JATS XML"]
  research --> cite["CSL and BibTeX citations"]

One source document goes through the schema and Core, then out to web, Markdown, and the optional Research exports.

Current status

Currently, there is a playground website demo to test Publisle's full functionality and experimental features which are still in progress, like the Rust research paper PDF compiler, interactive elements testing, with all the standard blocks needed for static blogging.

Example workflow

A concrete workflow is the Core quickstart. You write the article in Markdown, publisle validation cli command, then build the article to produce static output and open HTML output index for preview.

publisle validate article.md
publisle build article.md --out dist/

Next steps

I want to keep working on the experimental features that are still in progress: the Rust research paper PDF compiler, and interactive elements testing. I also want to keep checking the Core compile path against the reason I started: a portable standard I can use on my own site, with a lightweight compiled reader, portability between frameworks, and an addon for research paper export.

Links and references

  • publisle/publisle: Source repository for the Publisle document standard and tooling.

  • Publisle website: Project site and documentation home.

  • Documentation: Guides, standards, and integration docs.

  • Playground: In-browser Markdown editor, article preview, and an interactive FFT example.

  • JATS: Journal Article Tag Suite, a Research-profile export target.

  • LaTeX Project: Typesetting system used for Research-profile LaTeX and PDF export.

  • Citation Style Language: Citation and bibliography styles used via citeproc in the Research profile.

  • BibTeX: Bibliography format the Research profile can import and retain.

  • CommonMark: Markdown specification Publisle converts to and from, along with GFM.

  • GitHub Flavored Markdown: GFM extensions such as tables, task lists, and footnotes at the Markdown boundary.

Project log 1

Posts that follow this project, newest first.