Markdown authoring

What authoring a page as Markdown looks like, and what actually builds today.

This repository also carries a small, separate scaffold project,

md-theme-demo/

, built around a

# include <markdown.ARKlight>

directive that, according to its own README and

site.py

comments, turns a folder of

.md

files into pages with no

@site.page(...)

Page(...)

tree at all.

Building

md-theme-demo/

against the ARKlight version installed for this patch's

main

branch (v0.70.1) fails:

arklight build

rejects

# include <markdown.ARKlight>

at the preamble-resolution stage, naming the two directive forms that do exist there --

<stdlib.ARKlight>

and

<acc.<dotted.module.path>>

. On the

alpha

branch it builds correctly -- confirmed with a real

arklight build

md-theme-demo/

and of

examples/markdown-island/

, both producing

# include <markdown.ARKlight>

output with the

reading

markdown_theme

preset. Verify with

arklight search Markdown

or a real build against whichever branch you have installed before relying on it.

The content is still worth carrying over, since it's a clean demonstration of the inline markup and block types this site already renders through

components/render.py

: inline code, links, lists, a table and a note card. What follows is that same content, carried by hand into this site's own

title

description

blocks

shape, since this site itself still targets

main

rather than

alpha

There is also a real, buildable version:

examples/markdown-island/site.py

now uses the real

# include <markdown.ARKlight>

directive and

Site(markdown_theme="reading")

directly -- content/index.md, not a hand-written Page(...) tree -- built against the

alpha

branch. It builds on its own and is nested into this site's own output at

/examples/markdown-authoring/live/

open it

and use the link at the bottom to come back.

What it can hold

A paragraph can carry

inline code

and a

link back to the ARKlight repository

. The original Markdown version could also carry italics and bold; this site's own inline parser (

components/render.py

) only understands backtick code and

[label](href)

links, which is part of why the rest of this page is plain prose rather than a reproduction of that formatting.

A short list

Headings would become ark-md-h1 through ark-md-h6 in the original markdown-theme build, each with a slugged id.
Paragraphs would be ark-md-p.
This bullet list would be ark-md-list / ark-md-item there; here it renders through this site's own List and Item components instead.

A numbered list

Fenced code blocks would become ark-md-pre / ark-md-code-block.
Blockquotes would become ark-md-blockquote.
A pipe table would become ark-md-table.

A code block

# include <stdlib.ARKlight>
# include <markdown.ARKlight>

site = Site(markdown_theme="dark")

A blockquote

Markdown-as-content was meant to be opt-in, and not a second syntax for

Page(...)

-- a page that needs

State

Bind

, or a custom component still goes through a

@site.page(...)

-decorated function.

A table

Preset	Site(markdown_theme=...)
Light	"light"
Dark	"dark"
Reading	"reading"

See

md-theme-demo/

in this repository for the original files, and

gotchas

and

sourcemaps and debugging

for more on how ARKlight reports an unrecognized include directive like this one.