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
- Use the uncompiled repo as a template for your new repo.
- Write your content in
README.md(or any markdown file in any subdirectory you prefer). - Configure your site using config.json file.
- 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:
| Do Tables Work? |
|---|
| Yup! |
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!');
```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
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,
- You'll need to write the links in HTML (because nested markdown links are a mess to parse).
- 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).
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.
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.
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. So, not really a blog.
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.