This repository contains content to publish through the blog and dev.to. It has been structured as follows:
01_ideascontains content ideas with a brief description of what the post might be about. This is ideal for ideation and initial research. There's a basic template to copy to serve as a starting point for new ideas that eventually become posts.02_draftsis where drafting posts is done. In other words, this is where most of the work happens until a post is published by moving it to the03_postsdirectory. Each post follows Markdown format with a YAML headmatter to declare metadata related to it (i.e.,published,keywordsetc.).03_postscontains published content. The website picks this up automatically and the content has to be published separately to dev.to while using a canonical link pointing to the website to gain SEO benefits.imagescontains images included to the posts. Ideally these should be optimized already since there are no guarantees that publishing platforms (website, dev.to) would do it for you. Kraken is a good option for web-based optimization.emails/draftscontains planned messages, andemails/sentarchives messages after delivery. See email draft conventions.
For published posts, use <slug>.md; the filename becomes the URL slug on the
website. Existing posts use short snake_case slugs such as
what_are_serifs.md.
The posts should look like this:
---
title: "My awesome post about some font feature"
published: 2024-10-18
updated: 2024-10-25
keywords: ["typefaces"]
authors: ["Muster Mann"]
---
Brief introduction to the topic that pulls the reader in should go here. It should give a promise of what is to come and generate interest.
## First point
This is where content should go.

## Second point
More content goes here.
## Conclusion
This is the point where to recap the main point and potentially do a call to action and the a link follows this sentence as an example: [more information can be found at MonoLisa website](https://monolisa.dev).For simple posts, only heading level 2 should be used as in the sample. A good length for a short post can be anywhere between 500 to 2000 words. The main point is to use clear headings to give the post a clear structure and to make it easy to scan.
Lead each comparison with a short introduction and the detailed specimens. Follow the visual comparisons with the recommendation and trial links, then the comparison table near the end. End with Measurement notes recording the tools, versions, commands, scope, and limitations behind the reported measurements; clearly mark unmeasured fonts in deferred drafts. Put these notes inside a collapsed <details> element with <summary>Measurement notes</summary>, after the infographic disclosure when present. Omit the open attribute so this secondary information stays optional in the reading flow.
Aim for 300–500 words of main prose, excluding headings, the comparison table, the optional infographic, and Measurement notes. Use one or two sentences beside each specimen to identify a visible difference and point to a specific letter, operator, or spacing choice. Let the images demonstrate the comparison. Keep feature-tag lists, weight inventories, and measurement details in the reference sections, and avoid repeating specifications in the introduction and recommendation. The landing page's focus on distinction, italic construction, width, and spacing is useful inspiration; ground each comparison in the actual specimens. Keep draft review tasks in editorial comments and do not invent observations for deferred comparisons.
Connect the introduction to a reader's setup, such as italic comments, narrow editor panes, or a Powerline prompt. Name a visible difference or similarity before inviting readers to inspect it; avoid paragraphs that could describe any font pair. Keep technical measurement terms in the notes. Recommendations should identify one or two relevant reasons to choose each font. Comparison tables report features without a “Better fit” or winner column: more weights, axes, or supported languages do not automatically make a font the better choice for a particular reader.
Describe grade as stroke-thickness adjustment independent of the selected weight. Monospaced weight axes can preserve character advances too; do not present unchanged spacing as a grade-specific comparison advantage without checking the other font's weight axis. Distinguish this from MonoLisa Text, where grade preserves spacing and line breaks that weight changes can alter.
Every comparison post must include a summary infographic before publication, in addition to its detailed specimens. Put it in a collapsed <details> element after the comparison table and before Measurement notes, with <summary>View comparison infographic</summary>. Use an <img> referencing /images/comparison-monolisa-vs-<typeface>-summary.svg, with alt text naming the compared fonts and width="100%". Omit the open attribute so the graphic is optional in the reading flow. The infographic must match the post's measured font version and scope; explain any coverage or speaker-count estimates alongside it inside the disclosure. Retain the infographic when rewriting the prose. Berkeley Mono is an editorial exception: its redundant infographic was removed and the information consolidated into the comparison table.
Drafts awaiting verified comparison data should track the infographic as unfinished work rather than publish a graphic with guessed values. See the comparison series plan for the template and graphics workflow.
Where the copy identifies a particular letterform difference, add an enlarged detail with a soft accent-colored circle behind the relevant part of each font's glyph. Use brief, neutral captions and retain the complete specimen below. The detail pairs stay adjacent on mobile. Highlight definitions live in scripts/comparison-focus.mjs; regenerate the affected desktop and mobile SVGs with node scripts/render-comparison-svgs.mjs scripts/comparison-fonts.local.json --focus-only. Add a font key before --focus-only to render one comparison. These details use actual font outlines at equal nominal sizes, with separate upright/italic files where available. Fira Code's comparison explicitly labels its software slant: a 10° shear of the upright font, matching the angle recorded in MonoLisa's italic file. Use the same synthesis in the enlarged details and full code specimen, and document the angle in Measurement notes. Berkeley keeps its documented independently enlarged vendor outlines and uses scripts/render-berkeley-details.mjs.
Terminal graphics follow the landing page's “Symbols for Terminal” treatment: matching terminal windows with colored Powerline prompt segments, a box-drawing table, standard Unicode block progress bars, and a compact status line. Both fonts use identical content, size, line height, and theme colors. Render all symbols from the measured font files, including the separators; do not draw replacement arrows or use a fallback font for missing glyphs. Use standard blocks rather than MonoLisa's private-use progress symbols for this shared coverage comparison. Stack the windows on mobile. Regenerate with node scripts/render-comparison-svgs.mjs scripts/comparison-fonts.local.json --terminal-only; the layout lives in scripts/render-terminal-comparison.mjs. Apply this format to deferred comparisons once their licensed font files are available.
The JetBrains Mono comparison also shows default and alternate zeros from both fonts and MonoLisa's grade adjustment at a fixed Regular weight. The grade graphic demonstrates stroke thickness at the same weight; the prose acknowledges that both monospaced fonts also preserve spacing when weight changes. Regenerate their desktop and mobile SVGs with node scripts/render-comparison-svgs.mjs scripts/comparison-fonts.local.json jetbrains-mono --controls-only. The layout lives in scripts/render-comparison-controls.mjs; it verifies equal advances across the grade samples and keeps the enlarged zero comparisons adjacent on mobile.
Most of the edits can be done directly through GitHub user interface on web. It may be possible images may have to be added through Git repository, though.
Run npm install to install dependencies and enable the Git pre-push hook.
Before each push, the hook compiles every Markdown file directly inside
02_drafts and 03_posts, plus faq.md, as MDX. It checks the committed
content at each outgoing branch or tag, reports invalid syntax with a file,
line, and column, and blocks the push on failure. Fixes must be committed
before pushing again.
To check your working files, including new drafts, run npm run check:mdx.
The publishing workflow runs the same check before uploading content.
Editorial comments must use MDX syntax: {/* comment */}.
Preview a promotion without changing files or contacting external services:
npm run publish:draft -- 02_drafts/my-post.md --dry-runThen publish it to the MonoLisa website:
npm run publish:draft -- 02_drafts/my-post.mdThe command uses today's local calendar date for published and for updated
when that field is present, removes draft metadata, and moves the file to
03_posts without renaming it. It uploads the post and every referenced local
image to Vercel Blob, revalidates the website, and deletes and revalidates the
obsolete drafts/<filename> Blob object. It uses the same .env.private Blob
and website-revalidation credentials documented below.
To publish the same article to dev.to, configure these additional values:
DEVTO_API_KEY=...
DEVTO_SESSION_COOKIE="_dev_to_session=..."
MONOLISA_POST_BASE=https://www.monolisa.dev/postsDEVTO_SESSION_COOKIE is needed when the post contains images. Copy the
Cookie request header from an already signed-in dev.to browser session into
the private environment file; do not commit or share it. The command fetches a
fresh CSRF token itself and verifies that the browser session belongs to the
same DEV account as DEVTO_API_KEY.
Then opt in with --devto:
npm run publish:draft -- 02_drafts/my-post.md --devtoDEV receives a canonical URL pointing to the MonoLisa post, but its image
copies are kept separate from MonoLisa's Blob storage. Raster images are
uploaded unchanged to DEV's image storage. Its uploader does not accept SVG,
so SVGs are converted in memory to PNG with rsvg-convert before upload. The
SVG remains unchanged in the repository and on Blob, and the generated PNG is
not written into images/.
Collapsed <details> blocks with a plain-text <summary> are converted to
DEV's Liquid disclosure format. This keeps the
optional comparison infographic and Measurement notes collapsed; DEV strips
the raw HTML wrapper.
Install librsvg so
rsvg-convert --version works before publishing an SVG-bearing post. DEV does
not expose image upload through its API-key API, so this command uses the same
session-authenticated /image_uploads endpoint as DEV's editor. That endpoint
is internal and may change; an expired session fails with a prompt to refresh
DEVTO_SESSION_COOKIE.
By default, DEV tags are derived from the post keywords. Override them with
--tags "fonts,typography" (at most four), or use --series "Series name".
The script stores the DEV article id and the successful DEV image URLs in the
ignored .devto-state.json file. Image entries are keyed by a content hash, so
retries reuse uploaded copies when the source has not changed. The script also
checks existing articles by canonical URL before creating one, which makes
retries update the same article.
DEV article bodies tag MonoLisa website links with utm_source=devto,
utm_medium=syndication, utm_campaign=blog-syndication, and a post-specific
utm_content. The canonical URL and website Markdown remain clean. Existing
DEV articles can be refreshed with the same publish:draft --devto command,
using their original 02_drafts/<slug>.md input path; the command resumes from
03_posts/<slug>.md when the draft is already published. Preview with
--dry-run first.
All credentials are validated before the local move. Once the local promotion
succeeds, a later Blob or DEV failure is intentionally not rolled back. Run the
same command again: when the draft is absent and the matching file already
exists in 03_posts, the script resumes the external publication without
changing its publication date. Use --date YYYY-MM-DD to select an explicit
date for a new promotion.
Warning
Drafts are public editorial content, not confidential material. Publishing a
file from 02_drafts uploads it to a publicly readable Blob URL.
Install dependencies once with npm install, then add the publishing
credentials to the ignored .env.private file:
BLOB_READ_WRITE_TOKEN=...
WEBSITE_REVALIDATION_URL=https://www.monolisa.dev/api/revalidate/blob
WEBSITE_REVALIDATION_SECRET=...The revalidation URL is the full website endpoint, and the secret must match
the website's REVALIDATION_SECRET. All three variables are required for a
real publish. A dry run requires no credentials and makes no network requests.
Pushes to main automatically publish the current FAQ, blog drafts, posts,
email draft previews, and referenced images when relevant files change. The
workflow runs the test suite first, uploads the objects to Vercel Blob, and
then revalidates the corresponding website caches. Concurrent runs are
serialized so two commits cannot write and revalidate at the same time.
Configure these GitHub Actions repository secrets before enabling the workflow:
BLOB_READ_WRITE_TOKENWEBSITE_REVALIDATION_URLWEBSITE_REVALIDATION_SECRET
Use the same values as the local .env.private file. The workflow can also be
started manually from the repository's Actions tab. A full run removes
email preview payloads whose source draft has moved or been deleted. Other
published Blob paths still require explicit unpublishing.
Publish every blog draft, post, email preview, and the FAQ with:
npm run publish:content -- --allImages referenced by the selected Markdown files are uploaded before the
content. Both Markdown image syntax and HTML img/source elements are
supported. Image objects keep their repository paths, such as
images/example.svg. Publishing a post or the FAQ stops if a referenced local
image is missing; draft placeholder images produce warnings instead. After all
uploads finish, the publisher invalidates the corresponding website caches. It
omits image context so both published and draft cache variants are refreshed.
To create or update only selected objects, pass files or one of the content directories instead:
npm run publish:content -- 02_drafts/my-draft.md
npm run publish:content -- 03_posts/my-post.md
npm run publish:content -- 02_drafts
npm run publish:content -- faq.mdImages can also be published directly, either individually or as a directory:
npm run publish:content -- images/example.svg
npm run publish:content -- imagesDrafts are stored at drafts/<filename> and published posts at
posts/<filename>. Email previews are JSON payloads at
mail-previews/<filename>.json; the website serves them at
/mail-previews/<filename>. The FAQ is stored at faq.md. These are stable
public URLs;
an update can take up to a minute to propagate through Vercel Blob's cache. Use
--dry-run to inspect both the uploads and cache invalidation payloads without
contacting Vercel.
Warning
Publishing creates or overwrites objects; it does not delete old Blob paths. Moving or deleting a source file requires explicitly unpublishing the old object.
If website revalidation fails, the Blob uploads have already succeeded. Retry only the safe final step for each pathname reported by the publisher:
npm run website:revalidate -- --pathname images/example.svgEvery DEV article should have a topic-specific 2000 × 840 PNG cover. Designs, outlined SVG sources, the gallery, and research notes live in social_media/devto.
npm run render:devto-covers
npm run publish:devto-covers -- --all --dry-run
npm run publish:devto-covers -- --allPass a post slug instead of --all to update one cover. The publisher uses
DEVTO_API_KEY and BLOB_READ_WRITE_TOKEN, hosts immutable cover assets under
the separate devto-covers/ Blob prefix, and changes only the cover of an
existing published article. It does not republish the body or create posts.
Run it after publish:draft --devto for a new post with a registered cover
design. The regular article publishers omit the cover field, preserving covers
when updating article text.
The friction series can be prepared for dev.to with:
node scripts/publish-friction-to-devto.mjs --dry-run --create-drafts --canonical-base https://monolisa.dev/postsThe command above is a dry run and does not call the dev.to API. To create unpublished dev.to drafts, add a private .env.private file:
DEVTO_API_KEY=...Then run:
node scripts/publish-friction-to-devto.mjs --create-drafts --canonical-base https://monolisa.dev/postsThe script stores dev.to article ids and URLs in .devto-friction-state.json, which is ignored by Git. After draft creation, it updates the drafts once more so crosslinks inside the friction series point to the corresponding dev.to articles while canonical_url still points to the MonoLisa website.
After reviewing the drafts on dev.to, publish them with:
node scripts/publish-friction-to-devto.mjs --publish --canonical-base https://monolisa.dev/postsThe syndicated friction bodies use the same DEV campaign tags on links back to
the MonoLisa website. Crosslinks that stay on dev.to are left alone. Running
the --publish command again refreshes existing articles with attributed links.
For a body-only update of existing DEV articles, run:
node scripts/refresh-devto-attribution.mjs --dry-run
node scripts/refresh-devto-attribution.mjs --applyThis reads the two local DEV state files, fetches each live article, verifies its canonical URL, and updates only articles with untagged MonoLisa links. It backs up the original bodies to an ignored local JSON file before writing.