Dmitry VerkhoturovandGitHub
fb7b6c2cdd
* Serve the build-independent web assets from the backend `privacy.html`, `markdown-help.html` and the `400x400.jpeg` it embeds carry no template variable, link no script or stylesheet, and are imported by nothing in the widget. They now live in `backend/app/webassets/assets`, embedded there, and are served under `/web` alongside the frontend build. `/web` reads the frontend build first and falls back to them, which is what lets an operator replace one by dropping a file into `--web-root`. That is what `privacy.html` needs: it describes remark42.com, while the authorization guide tells operators to hand its URL to Google and Facebook as their own application's privacy policy. Only a missing file falls through. An unreadable file in the web root keeps reporting as unreadable rather than being silently replaced by the embedded copy, and a name the filesystem rejects reports as missing rather than as a server error, both matching what `http.Dir` did. The dev server serves the same directory, so the Markdown help link in the comment form resolves on the dev port as well as in production. The two pages are served as they are written. `markdown-help.html` was minified before, and its formatted inline stylesheet is most of its 8.5 kB; that is 2.4 kB more over the wire, behind the hour-long cache header the file server already sets. Drops `copy-webpack-plugin`, which had no other pattern, and the stylelint entries that only ever matched these files. * Make pnpm dev:app start again The dev server has been failing to start on two counts, so the flow the contributing guide documents does not run at all. `webpack-cli` 4 drives `webpack-dev-server` 5 through the argument order of an older major, handing it the compiler where it expects the options object. It rejects that against its schema and exits, complaining about an unknown `_assetEmittingPreviousFiles` property, which is a field of the compiler. `webpack-cli` 7 is the release that declares `webpack-dev-server` 5 as a peer. Past that, `http-proxy-middleware` resolves to 4.1.1, which no longer accepts the two-argument call `webpack-dev-server` makes, so the `/api` and `/auth` proxies throw on startup. It is pulled in by the security override for CVE-2025-32996, the only override in the file with no upper bound: `>=2.0.10` matches every later major. Bounding it to the 2.x line keeps the fix and the API `webpack-dev-server` calls. With both in place `pnpm dev:app` serves the widget and the pages under `/web` on port 9000.
Remark42 site
Sources for remark42.com, built with Hugo.
Requirements
Hugo, the plain build; nothing here needs the extended one. The version the published image builds with is ARG HUGO_VERSION in Dockerfile, and any release at or above it works locally. Nothing updates that pin automatically: Dependabot's docker ecosystem reads FROM references, and the Hugo version is a bare string in a download URL, so bumping it is a manual edit. brew install hugo, or see the installation guide. Nothing else: no Node, no package manager.
Development
hugo server
Serves the site on http://localhost:1313 and rebuilds on change.
Alternatively, without installing Hugo:
docker compose up
Build
hugo --minify --cleanDestinationDir --destination build
Writes the static site to build/, which is what the Docker image serves. --cleanDestinationDir matters on a rebuild: without it a page you deleted, and the fingerprinted stylesheets of earlier builds, stay behind.
Layout
| Path | Contents |
|---|---|
content/ |
Pages as markdown. content/docs/ is the documentation tree |
layouts/ |
Templates. partials/, shortcodes/ and _markup/ render hooks |
assets/ |
styles.css and the scripts, fingerprinted at build time |
static/ |
Files copied to the site root as-is: favicons, manifest, robots.txt |
data/nav.json |
The documentation sidebar |
hugo.toml |
Site configuration |
Writing docs
A page is a markdown file with a title in its front matter. A directory becomes a section when it holds _index.md, and a page that carries its own images is a directory with index.md and the images beside it.
Adding a page to the sidebar means adding an entry to data/nav.json; the paths there are relative to /docs.
Callouts use the note shortcode, which takes the emoji to show:
{{< note "💡" >}}
Anything markdown here.
{{< /note >}}
Two documentation pages are symlinked into the repository as backend/README.md and frontend/apps/remark42/README.md, so moving or renaming content/docs/contributing/backend/index.md or content/docs/contributing/frontend/index.md means repointing those symlinks.
Styling
assets/styles.css is hand-written, with the palette and light/dark values as custom properties at the top. The dark theme is applied by a dark class on <html>, set before first paint by assets/inline.js and toggled by assets/script.js.
Code highlighting is Hugo's built-in Chroma. The rules at the end of the stylesheet come from hugo gen chromastyles --style=github and --style=github-dark.
Dates
The "Updated" line on a documentation page comes from .Lastmod. hugo.toml resolves it through [frontmatter] lastmod, which tries git, then a lastmod in the page's front matter, then the file's modification time; without that chain it would resolve to .Date and every page would read Jan 01, 0001. A deployed page therefore shows the build date, since a checkout does not preserve modification times.
HUGO_ENABLEGITINFO=true hugo gives real per-page commit dates. It is off by default because the image build context is site/ alone, where there is no .git for Hugo to read and it fails rather than falling back.