Build a very simple web browser whose native document format is Markdown.
This is not a Markdown editor inside a conventional web app.
It is a browser for a simpler web.
The content is Markdown files linked to other Markdown files. The browser understands enough Markdown to render documents cleanly and navigate between them.
The format must stay simple enough that the same documents can later be rendered as other kinds of interfaces:
- HTML pages
- SVG outlines
- directed graphs
- HyperCard-style cards
- OPML
- RSS
- other formats we have not thought of yet
The Markdown documents are the canonical data.
Presentation is secondary.
Do not allow the format to evolve into HTML/CSS/JavaScript.
Do not add features merely because conventional browsers have them.
The system should remain understandable by one programmer reading the source.
Avoid frameworks.
Avoid build systems unless absolutely necessary.
Avoid client-side application architectures.
Use JavaScript.
Use Node.js on the server.
Use ordinary browser JavaScript and jQuery where useful.
The first real site built with this browser will be Scripting News.
I want to begin writing blog posts directly into this environment.
That means the first implementation should be useful for daily writing and browsing, rather than being a technology demonstration.
A document is an ordinary Markdown file.
Example:
# October 6, 2026
I've been thinking about what the web would look like if the
document format had remained simple.
Maybe the browser should understand Markdown directly.
- [Previous day](2026/10/05.md)
- [Home](index.md)The browser loads this file and displays it.
Links to Markdown documents should remain inside the Markdown Browser.
External links should behave like normal web links.
Internally, every Markdown file should be parsed into a simple document tree.
The internal representation should contain semantic structure, not presentation.
Conceptually:
{
title: "October 6, 2026",
url: "/2026/10/06.md",
nodes: [
{
type: "heading",
level: 1,
text: "October 6, 2026"
},
{
type: "paragraph",
text: "I've been thinking..."
},
{
type: "list",
items: [...]
}
]
}Do not expose Markdown parser-specific structures throughout the program.
Create a small normalized structure that belongs to this project.
This is important because other renderers will eventually consume the same structure.
For example:
Markdown file
|
v
Markdown parser
|
v
Simple document model
|
+------ HTML renderer
|
+------ SVG renderer
|
+------ HyperCard renderer
|
+------ OPML renderer
The parser should know Markdown.
The renderers should know the document model.
They should not need to know Markdown syntax.
Start with standard Markdown.
Support:
- headings
- paragraphs
- bold
- italics
- links
- images
- unordered lists
- ordered lists
- blockquotes
- code
- code blocks
- horizontal rules
Do not invent extensions until a real use requires them.
Navigation is the first area where a very small extension may be useful.
Ordinary Markdown links already provide most navigation.
[Yesterday](2026/10/05.md)The browser should recognize that this points to another Markdown document and load it into the browser.
The URL in the browser should change so pages have stable, bookmarkable addresses.
Browser Back and Forward should work.
Reload should work.
Opening a Markdown document directly by URL should work.
These are internal:
index.md
about.md
2026/10/06.md
../index.md
These are external:
https://example.com/
http://scripting.com/
Internal Markdown links are intercepted by the browser.
External HTTP links are handed to the conventional browser.
We may eventually need a small amount of metadata.
Use YAML-style front matter only if needed.
Example:
---
title: Scripting News
created: 2026-10-06T20:00:00-04:00
---
# Scripting NewsDo not require metadata.
A plain Markdown file must always be valid.
Prefer information that can be inferred from the document itself.
For example, the first H1 can be the title.
If we discover that links in the body are insufficient, allow a few semantic fields:
---
title: October 6, 2026
previous: 2026/10/05.md
next: 2026/10/07.md
home: /index.md
---These represent relationships between documents.
They do not specify where buttons appear or what they look like.
That distinction is important.
Metadata describes structure.
The renderer decides presentation.
Do not allow things like:
font-size
background-color
margin
column-width
float
position
There should be no document-level CSS.
There should be no per-document styling.
The browser itself owns presentation.
Keep the browser interface minimal.
Initial version:
-------------------------------------------------
Markdown Browser
< Back Forward > Home
-------------------------------------------------
October 6, 2026
I've been thinking about what the web would
look like...
-------------------------------------------------
The page content is the dominant part of the window.
Navigation chrome should be small.
The browser should have one pleasant built-in reading style.
Readable type.
Reasonable line length.
Good spacing.
Nothing configurable initially.
The absence of design choices is part of the design.
Documents should not control their visual appearance.
A site should be able to look like this:
site/
index.md
about.md
2026/
10/
06.md
05.md
images/
photo.jpg
Relative Markdown links should work naturally.
Create a small Node.js server.
Responsibilities:
- serve Markdown documents
- serve images and other static files
- serve the browser application
- resolve paths safely
- optionally provide a simple API for loading documents
Do not introduce a database.
The filesystem is the database.
markdownbrowser/
server.js
lib/
parseMarkdown.js
documentModel.js
client/
index.html
browser.js
renderHtml.js
site/
index.md
Later:
renderSvg.js
renderOpml.js
renderCards.js
Keep each renderer independent.
Conceptual flow:
User clicks link
|
v
Resolve document URL
|
v
Fetch Markdown
|
v
Parse Markdown
|
v
Normalize document model
|
v
Render
|
v
Update browser history
Use browser history APIs.
A loaded Markdown document should have a URL representing that document.
Back and Forward should move between documents without special application concepts.
Do not create a parallel navigation stack.
Use the web platform's existing one.
Editing is not part of version 1.
First build the browser.
Once browsing feels right, add writing.
Eventually I should be able to edit the current Markdown document and save it.
But do not mix editing architecture into the first implementation.
The project should include a small test Scripting News site.
Example:
site/
index.md
2026/
10/
06.md
index.md:
# Scripting News
A weblog started in 1994.
## October 2026
- [October 6](2026/10/06.md)2026/10/06.md:
# October 6, 2026
Imagine a Markdown web browser.
No CSS, frameworks, just Markdown.
Maybe a few small extensions for navigation.
But it never gets more complicated.
And it makes it easy to convert it to webs of other things,
like SVG or HyperCard cards.
[Home](../../index.md)This should be enough to demonstrate the first version.
The same document model should later support an SVG renderer.
A Markdown document might become a node.
Links become edges.
For example:
[Home]
|
+------+------+
| |
[Oct 5] [Oct 6]
|
[Another post]
The SVG view should not require changes to the Markdown documents.
Markdown headings already imply hierarchy.
For example:
# October 6
## Web
Some thoughts.
### Markdown Browser
More thoughts.This can naturally become an expandable outline.
The outline is another view of the same document.
A Markdown document can also be interpreted as a card.
One file = one card.
Links move between cards.
Front matter could provide card relationships if necessary.
Example:
+-----------------------------------+
| October 6, 2026 |
| |
| Imagine a Markdown web browser. |
| |
| [Yesterday] [Home] [Tomorrow] |
+-----------------------------------+
Again, no change to the underlying document.
Eventually the browser should understand the collection as a graph.
Documents are nodes.
Links are edges.
That graph can be rendered many ways.
This makes Markdown more than a page format.
It becomes a simple interchange format for interconnected documents.
Do not build:
- React
- Vue
- Angular
- a component system
- a CSS framework
- plugins
- themes
- user-defined CSS
- JavaScript embedded in Markdown
- Markdown components
- JSX
- MDX
- a database
- authentication
- collaboration
- a package ecosystem
- an extension marketplace
If one of these appears necessary, stop and reconsider the design.
Every new feature should pass this test:
Does this add meaning to the document, or merely presentation machinery?
Meaning may belong in the format.
Presentation machinery probably does not.
A second test:
Could a competent programmer understand the entire Markdown Browser format in ten minutes?
The answer should remain yes.
Version 0.1 is complete when:
- The Node server starts with one command.
/opens the Markdown Browser.index.mdrenders correctly.- Clicking a relative Markdown link loads another document.
- External links open normally.
- Back and Forward work.
- Images work.
- Reloading a document URL returns to the same document.
- The implementation contains no application framework.
- Five or ten Markdown files feel like a small navigable website.
Do not implement SVG, HyperCard, editing, OPML, RSS, plugins, or customization yet.
The purpose of version 0.1 is to answer one question:
Is browsing a web made entirely of Markdown pleasant enough that I want to start writing Scripting News in it every day?
If the answer is yes, continue from there.