Building a Connected Engineering Blog with Next.js

An engineering blog becomes much more useful when an article is not an isolated page. It should remain readable as ordinary prose, connect to the work around it, expose enough structure for search engines and machine readers, and require almost no publishing maintenance. This article is both an explanation of that system and a working demonstration of its features.

The publishing boundary is intentionally simple: Markdown owns the writing, Next.js owns the presentation, Git owns the history, and Vercel owns the deployment. Everything between the source file and the final page is compiled and checked automatically.

The publishing pipeline

A note begins as local Markdown. Frontmatter gives it a stable title, summary, dates, tags, aliases, and publication status. The build then validates the metadata, resolves internal references, calculates the indexes, and renders static HTML.

The important design decision is that publication is explicit. A file is eligible only when it is inside a public collection and has publish: true. That makes private working material structurally different from public writing, instead of depending on memory or a fragile ignore rule.

Frontmatter as a contract

The metadata is validated before a deployment can succeed:

title: "Building a Connected Engineering Blog with Next.js"
publish: true
status: reference
created: "2026-07-17"
updated: "2026-07-17"
tags:
  - Next.js
  - software engineering

The three publication statuses describe the editorial state without turning writing into a metaphor:

Missing titles, malformed dates, duplicate routes, unresolved public links, missing images, and secret-like values stop the build. The goal is not merely automation; it is automation that protects the public output.

Connections are part of the content model

Markdown links and Obsidian-style wikilinks are resolved during the build. For example, Udayapur District points to a published page by alias. The reader receives a normal accessible link in the final HTML, and the target article receives a backlink automatically.

For every entry $v$, the compiler records its outgoing links. Reversing those edges produces backlinks:

That one index powers several interfaces:

• connected articles at the end of a page;
• backlinks from pages that cite the current article;
• related entries inferred from shared links and tags;
• the force-directed knowledge map;
• hover previews that preserve reading context.

This is useful for technical writing because architecture decisions rarely live alone. A deployment article may depend on a caching note, a database trade-off, and an incident review. Explicit links preserve that reasoning better than a chronological archive can.

The force-directed knowledge map

The knowledge map treats articles as particles and explicit links as springs. Connected entries pull toward one another, repulsion keeps labels legible, collision prevents overlap, and a weak centering force keeps the system in view. The simulation loses energy and settles, but a reader can drag a node to reintroduce motion.

A simplified force for node $i$ is:

Circle radius is derived from the article's word count, so long-form references carry more visual weight than short notes. Hovering a circle reveals its title, collection, and length while emphasizing only the edges that connect it. Dragging, panning, and zooming make the map an exploratory index rather than a decorative diagram.

Technical prose should render like technical prose

The article renderer supports GitHub-flavoured Markdown, mathematical notation, syntax-highlighted code, diagrams, tables, lists, quotes, and deep heading structure. These are rendered into semantic HTML wherever possible so the page remains useful without depending on a client-only editor.

Mathematics with LaTeX

Inline expressions such as $O(n \log n)$ remain within the sentence. Display expressions use KaTeX, which gives fast and consistent mathematical typesetting:

Code with language-aware highlighting

Fenced code retains its language and exposes a copy control:

type PublicationStatus = "brief" | "developing" | "reference";


function canPublish(input: { publish: boolean; status: PublicationStatus }) {
  return input.publish && input.status !== "brief";
}

The example is deliberately small, but the same renderer handles command-line output, configuration, and larger implementation fragments.

Tables, tasks, and quotations

GitHub-flavoured tables and task lists work directly:

• validate public metadata;
• resolve wikilinks and backlinks;
• generate search, sitemap, feeds, and machine-readable text;
• render diagrams, mathematics, and highlighted code;
• keep improving the writing itself.

The publishing system should disappear during writing and become strict only at the boundary where private thought turns into public information.

Navigation for long-form reading

Every second- and third-level heading is extracted into a table of contents. The current heading is highlighted while the reader moves through the article, and the reading-progress control provides orientation on long pages. On smaller screens the same structure remains available without forcing a desktop sidebar into the reading column.

The site also provides:

1. command search with Cmd or Ctrl + K;
2. tag pages for topic-level browsing;
3. hover previews for internal references;
4. backlinks and related entries after the article;
5. stable canonical URLs and visible updated dates.

These interfaces share one compiled content model, so search, navigation, and the graph cannot quietly disagree about what has been published.

SEO and machine readability

Good discovery begins with complete server-rendered HTML. Each article receives a unique title and description, canonical URL, publication and modification dates, Open Graph metadata, and BlogPosting structured data. The generated sitemap and Atom feed enumerate public content, while semantic headings and links make the document understandable without executing the interactive parts of the site.

Machine readers receive two additional indexes:

• llms.txt describes the author, collections, and canonical entry points;
• llms-full.txt provides a Markdown-formatted corpus with canonical URLs, metadata, and full public text.

These files do not guarantee that any model will cite a page. They provide a clear, crawlable representation while normal search fundamentals—original writing, descriptive titles, meaningful internal links, stable URLs, and attribution—remain the foundation.

One source, several representations

The architecture deliberately derives every public representation from the same source:

That reduces editorial drift. Correcting a title or adding a connection updates the page, search result, graph label, feed metadata, and machine-readable corpus in the next build.

What the reader should notice

The system is broad, but the interface should feel restrained. The article is still the main object. Search is quick, the table of contents is quiet, link previews appear only when requested, and the knowledge map is available when a spatial view is genuinely useful.

This page demonstrates the full pipeline in one place: validated metadata, publication status, table of contents, LaTeX, Mermaid, code highlighting, tables, task lists, aliases, tags, wikilinks, backlinks, related entries, reading progress, structured data, feeds, sitemap inclusion, search indexing, and machine-readable full text. The best test is that all of those features are derived from an ordinary Markdown file that remains readable outside the site.