Syncpress documentation
Build static sites from ordinary files
Syncpress turns Markdown, HTML, Liquid templates, and local assets into a static site with repeatable output.
Syncpress builds content-oriented sites from a YAML configuration file, Markdown or HTML content, Liquid layouts, and ordinary local files. A successful build writes a directory for deployment to a static host.
Install the public @mit-sdg/syncpress package from npm as a development
dependency. It provides the syncpress executable and a programmatic API. This
documentation is also an independently installable example site.
Choose a starting point
- Build a site for a complete first project.
- Use the user guide for configuration, templates, assets, commands, and the programmatic API.
- Read how Syncpress is built when contributing to the repository.
What a build guarantees
Equal declared source paths, file bytes, and configuration produce equal output bytes. Those declared values are the complete publishing inputs. A build rejected before reconciliation preserves the previous output tree. See reconciliation failures for the filesystem assumptions at the final installation step.
Syncpress targets build-time static pages. Pages that require request-time state, API routes, database access, or arbitrary build-time code require another system.
What this example covers
This documentation is also a working Syncpress project. Its source demonstrates
front matter, Markdown, collections, partials, local links, copied assets, and
responsive images. Compare content/index.md
with this generated page.
picture with AVIF and WebP alternatives.
Links and collections
Build the example, trace the implementation, or inspect a verbatim HTML page. Syncpress resolves these content-relative links to their canonical routes while retaining query strings and fragments.
The documented collection uses an existence filter and currently contains 15 routed documents. The siteBuilding collection uses a list-contains filter, while the featured section below uses a boolean equality filter.
Featured documentation
Field note
Assets follow explicit references
Local links, downloads, SVGs, and primary raster images each take an explicit output path through the build.
Build guide
Build a Syncpress site
Create the required project files, render one Markdown page, and verify the static output.
How Syncpress is built
How Syncpress is built
The design boundaries, batch model, transactions, and selected composition paths behind Syncpress.
Field note
Routes begin with ordinary files
Derived paths and explicit claims make each published document predictable before a layout renders.
Field note
Why build a static site generator with a sync engine?
What synchronization adds to a static build, where the design pays off, and where an ordinary pipeline remains the better choice.
Recent implementation notes
Why build a static site generator with a sync engine?
What synchronization adds to a static build, where the design pays off, and where an ordinary pipeline remains the better choice.
A static site generator usually expresses its work as an imperative sequence that reads a directory, transforms each document, and writes another directory.
Syncpress uses synchronization when pages share routes, collections, templates, links, generated assets, and deployment files. Work that begins with one source file can affect output across the site. Publication begins after every required part of the build completes successfully.
Assets follow explicit references
Local links, downloads, SVGs, and primary raster images each take an explicit output path through the build.
The posts collection sorts data.date in descending order, so this note appears before older entries. Its collection card is limited to publication data and an excerpt.
Routes begin with ordinary files
Derived paths and explicit claims make each published document predictable before a layout renders.
Every routed document begins as a file below the content root. posts/first.md derives /posts/first/; a page can instead claim an explicit route in front matter.