A Markdown Non-Compiled Non-Blog

A platform for writing static content in markdown, reading it in Tufte-approved HTML, and publishing without ever needing to open a terminal (or even leave github, for that matter).

If you're looking for a specific piece of information that isn't on this page, check the directory

1. Use the uncompiled repo as a template for your new repo.
2. Write your content in README.md (or any markdown file in any subdirectory you prefer).
3. Configure your site using config.json file.
4. Publish using Github Pages.

All the usual features of markdown, made possible by Showdown, plus a few other goodies.

Simple tables can be rendered, like so:

It's just a regular markdown table.

| Do Tables Work? |
| --------------- |
| Yup!            |

Syntax Highlighting is made possible by highlight.js

console.log('Hello, World!');

In markdown, it's an ordinary code fence:

```javascript
console.log('Hello, World!');
```

Each code block also has a copy button that appears on hover, so readers can grab snippets without selecting text manually.

$\LaTeX$ is supported, via the excellent KaTeX. For example, Here's Bayes Theorem:

$$\Pr(A|B)=\frac{\Pr(B|A)\Pr(A)}{\Pr(B|A)\Pr(A)+\Pr(B|\neg A)\Pr(\neg A)}$$

And the markdown to represent it:

$$\Pr(A|B)=\frac{\Pr(B|A)\Pr(A)}{\Pr(B|A)\Pr(A)+\Pr(B|\neg A)\Pr(\neg A)}$$

Note the double dollar-signs. This denotes that the expression should be displayed on its own line. If you want to produce inline $\LaTeX$, use single dollar signs instead.

By default, uncompiled generates HTML for use with Tufte CSS. One prominent feature of this is almostI had to write some code to make it easy. See here, if interested.-out-of-the-box support for side- and margin- notes.

The way to accomplish this is by a minor abuse of the markdown link syntax.Hattip to Xmark, from which this syntax was cribbed. Just create a link for which the text is the content of the sidenote, and the link is simply sidenote, like so:

[And Here's the sidenote!](sidenote)

If you want to have a side note without a number, ...like this the syntax is the same except you link to marginnote instead:

[And Here's the marginnote!](marginnote)

Note: if you intend to place links in your side- and margin- notes,

1. You'll need to write the links in HTML (because nested markdown links are a mess to parse).
2. The link will need to extend from wherever it begins in the note to the end of the note (because nested markdown links are a mess to parse).

Mermaid diagrams are rendered directly from a fenced code block tagged mermaid, like so:

```mermaid
graph TD
  A[Write Markdown] --> B[Push to GitHub]
  B --> C[Site updates]
```

which renders as:

graph TD
  A[Write Markdown] --> B[Push to GitHub]
  B --> C[Site updates]

Mermaid supports flowcharts, sequence diagrams, Gantt charts, entity-relationship diagrams, and more. The diagram theme automatically follows the current dark/light mode setting.

While uncompiled is pretty opinionated about a lot of things (the type of servers it runs on, the layout of the pages, etc.) There are a few viable options.

You can add YAML frontmatter to any page to set its title and description. Place it at the very top of the file, enclosed in --- fences:

---
title: My Post Title
date: 2024-03-15
description: A short summary used in the page index and link previews.
tags: [writing, meta]
---

# Content starts here

The frontmatter block is stripped before rendering and never appears in the article. The title field overrides the browser tab title (otherwise derived from the first # heading), and description is written into <meta name="description">.

You can inline the contents of another Markdown file using the include: link syntax:

[](include:pages/bibliography.md)

This syntax renders as nothing in standard Markdown viewers (empty link text) but inlines the referenced file's content when viewed in uncompiled. Transclusion is recursive — included files can themselves include others — up to a depth of 5. Circular includes are detected and replaced with a warning rather than looping.

Add a pages.json file at the root of your repo to maintain a content manifest. Each entry looks like:

{
  "title": "My Post",
  "path": "pages/my-post.md",
  "date": "2024-03-15",
  "description": "A short summary.",
  "tags": ["writing"]
}

Once pages.json exists, the page index provides a filterable, searchable list of all your content — entirely client-side. See the pages.json documentation for the full schema.

Make a regular Markdown document. I like to put them in the pages/ directory, but you can put them wherever. Just put the relative path in the address when linking to it.

Every heading in a rendered page automatically gets a stable anchor link — hover over any heading to reveal the # link you can share to point readers directly to a section.

All the global configurations are stored in config.json. We also have a bit more documentation.

Addressing is managed through the q (for "query", but shorter) HTTP GET parameter. If you don't provide one, it attempts to load README.md (i.e. the document you're presently reading.) An explicit link to this document looks like this:

https://aaboyles.github.io/uncompiled?q=README.md

q is a relative path, so you can put content in another page and then reference it:

https://aaboyles.github.io/uncompiled?q=pages/AnotherPage.md

uncompiled uses Tufte CSS as its base style library, with a few minor overrides. If you'd like to further customize the styling, just edit the style.css file to suit your preferences.

I love the idea of moving as much computation as possible into the browser. Why do this horrible thing, you ask? Because browsers are awesome. Javascript has become outrageously fast and powerful, and everyone is allowed to run it. I often work in computing environments where I cannot install things, or even download and run unapproved executables. So do millions of other people. But we can all load webpages!

Even for those who can run executables, working in the terminal can be a challenging prospect if you're not already pretty experienced. That's what static blog compilers require. But if we just use javascript libraries to mediate the task of transforming the thing we want to write into the thing we want to see, then the only competencies the user needs are 1) using browsers and 2) writing markdown. (git is also very helpful for hosting.)

Uncompiled is a tool in this genre. No compiling, just write your markdown content and see it as HTML.

What's the difference between a blog and a more general website? I claim the fundamental difference is that blogs are platforms for dated content--whereas websites are the generalization of this that don't require that timestamping. This partly enables cool features like syndication.

We don't compile (see above), so we don't really know what's available the way blog-aware static site generators do. Other more conventional blog platforms (like Wordpress) stores and queries data from a server runtime, but we're restricted to just what can be accomplished with a file server (like Github pages provides) so we can't get an index of the pages at the time of pageload.

The bottom line is, there's no automated way to create the kinds of features we expect from blogs given the constraints I'm trying to respect. However, the pages.json manifest provides a manually-maintained index that gets you most of the way there — sorted listings, search, and a foundation for syndication — without a build step. So: not a blog, but closer than it used to be.

It doesn't work especially well with search indexing, so don't count on Google to drive a bunch of traffic to your site. The reason is that the resource that the user sees (crisply-formatted and styled HTML) doesn't exist for the web crawler--all that HTML is generated on-the-fly by the reader's browser. So this is not recommended if you want people to be able to find your content via searching. Works fine for link-sharing (e.g. email, social media) though.