-- prelude
This post is written in NeoDoc to provide
an example of what the format looks like.
A version with syntax highlighting and
live links is available >> here |
https://neodoc.style/blog/neodoc-and-the-atmosphere/ >>
if you'd like to read it that way.
-- tldr
I believe content portability is critical
to fulfilling the promise of a decentralized
internet. After all, being able to move your
content doesn't count for much if it doesn't
work anywhere else. You're implicitly
locked-in, even if you're seemingly in
control^^control^^.
A few years ago, I designed a plain-text
format to replace Markdown on >> my sites |
https://links.alanwsmith.com/ >>.
It's called NeoDoc and it offers a potential
solution for bringing portable, human-readable
content to the Atmosphere.
You can learn more about it at
>> neodoc.style | https://neodoc.style/ >>
-- title
NeoDoc and The Atmosphere
Hey folks,
While I've been on Bluesky for a bit, I
didn't really know about the Atmosphere until
recently. The more I learn, the more it has
my attention. I can't remember the last time
I was this excited about new tech.
My introduction was standard.site^^standard^^.
It made several appearances in my feed over
the past few weeks. I jumped^^jump^^ on it.
It's the kind of stuff I dream about^^manifesto^^.
I wasn't entirely sure how content worked
in standard.site and went looking for details.
One thing the leaflet^^leaflet^^ post I found
points out is that the lexicon is for content
discovery and social features. But,
-- blockquote/
Importantly, [it] is not a standard for
site content.
-- /blockquote
The only other^^other^^ post I've seen on a
content standard for the Atmosphere has to do
with a wordpress lexicon for publishing HTML.
-- h2
The Contenders
I submit that HTML could work as a standardized
content format. It's a battle tested standard
that renders natively in browsers without
modification. There are, however, a couple
things that recommend against it.
-- numbered/
1. It's not friendly to write by hand.
Unless you're hard-core, it's not something
most folks are into.
2. It's tough to standardize different
types of content. Microformats^^micro^^
were an attempt. They never took off.
That's at least in part because they lock
the content into the rendering layer. You
can do all kinds of things with CSS, but
you're stuck with a specific set of elements
and have to set up a separate parser if
you want to use the data in them
independently.
-- /numbered
Markdown^^md^^ is another option. It's easy to
learn and has huge market share in the developer
community. While it's great for blog posts,
it sucks for everything else. You can always
roll your own HTML to do interesting work.
But, you wind up back with its unwieldy
nature and parsing complexity.
The key feature missing from Markdown
is the ability to define content types.
For example, say you want to make a page of
book reviews with explicit styles for the
title, author, rating, and your thoughts.
There's no native way in Markdown to define
a container that provides access to the
individual pieces of data.
About the best you can do is define specific
positions for each piece of information and
write a custom parser to process and assemble
them^^mdbook^^. Possible, but you'd be better
off writing the HTML directly which leads
back to the same issues.
-- h2
Introducing NeoDoc
There are other content formats out there.
I reviewed a bunch when I got fed up with
Markdown and decided to switch to something
else for >> my various project websites
| https://links.alanwsmith.com/ >>.
None of the alternatives offered the combination
of flexibility and ease of use I was after.
So, I designed a new format. It's called
NeoDoc and you're reading it right
now^^maybe^^.
NeoDoc is designed to be simple to write
without sacrificing the power built into
HTML. The format breaks down like this:
-- list/
-- h3: The Details
- NeoDocs are built from sections. Each
one starts with two dashes and a name. For
example, we're currently in a ``list``
section.
Section names that don't end with a ``/``
keep going until the next section starts.
Section names that have a ``/``at the end
can wrap other sections. They go until they
hit the matching tag that closes them
(e.g. the ``-- /list``for this section
that you'll see below).
- Sections can have attributes like the
``-- h3: The Details``above. They're
available during rendering to do thing
like adding an ``H3``tag with specific
text above a list (which is what this one
does when this page is rendered to HTML).
- There's a pre-defined set of sections like:
``list``, ``checklist``, and ``numbered``.
You can also make ad hoc sections simply by
naming them. For example, you can make a
``-- book-review``section.
- Custom sections can have attributes just
like the pre-defined ones. So, we can make
a book review like this:
-- pre/
-- book-review
-- title: Dungeon Crawler Carl
-- author: Matt Dinniman
-- rating: 5 stars
-- tags: fantasy
Always trust the friends you've known
since third grade when they recommend
a book...
-- /pre
- Inline formatting and shorthands are
available for spans of text. For example,
you can wrap text in asterisks that
convert to HTML ``strong``tags during
rendering like:
**Alfa Bravo Charlie**
- Inline spans can also have attributes.
For example, here's a ``class``attribute
with the strong shorthand syntax:
**Alfa Bravo Charlie | class: green**
-- /list
That's it.
Sections, spans, and attributes.
A simple combination that turns out
to be incredibly powerful.
-- h2
Outro
I designed NeoDoc three years ago. It's
currently embedded in my personal static
site generator where it powers
>> something like three thousand pages |
https://www.alanwsmith.com/neo-files/report >>.
The format feels like a natural fit for
the Atmosphere. So, I'm extracting the
tools to make them independently available.
Once they're ready, I'll make them open
source so anyone can use them.
I'm incredibly excited about the Atmosphere.
I hope NeoDoc can become a part of it.
Because, if I'm right, the ability to
easily move the stuff we make to wherever
we want it will be key to practical
decentralization. I believe NeoDoc can
be instrumental in making that happen.
-alan
-- endnote
If you've got questions or feedback,
I'm all ears:
>> @al9000.com |
https://bsky.app/profile/al9000.com >>
-- endnote
I'd love to see NeoDoc become an active
participant in the Atmosphere. However, it's
way more important to me that general content
gets standardized on __something__, regardless
of what it is.
There will always be a need for custom formats
for specific applications. For everything else,
if we can't move it, it fails the promise
and potential of decentralization.
-- endnote
I didn't get into it here, but the section
and attribute approach NeoDoc uses effectively
turn content into a free-form database.
For example, you can aggregate all your
``-- book-review``content in one place.
Or, build something like Goodreads by
watching the fire hose for those sections
and building social features around them
(name-spacing is, of course, recommended).
The content will vary in how messy it is.
That's a feature. Not a bug. We've been living
so long in systems that force our content
into database schemas that we've forgotten
what a personal touch feels like.
NeoDoc provides structure for finding,
grouping, and laying out content without
forcing everything to fit rigid data
structures that prioritize storage over
creativity.
-- endnote/
I also didn't get into how transforming
content works. At the high level, the
reference NeoDoc app (when it's extracted
from my static site generator) performs
three functions:
-- numbered/
1. Takes a NeoDoc formatted input and
transforms it into a JSON formatted AST.
2. Transforms a NeoDoc AST into HTML
based on a standardized set of default
templates.
3. Accepts optional templates that override
the defaults when generating output.
-- /numbered
Collectively, that means NeoDoc can be
used out of the box to generate
standardized HTML. App can override the
templates to either supply their own
or pass in templates from the content
authors. The combination lets apps provide
complete control over the output with
the option to pass that control on to
the authors.
More details on templating will be in
the docs.
-- /endnote
-- endnote
Another thing Markdown suffers from is lack
of an official standard. Different,
competing standards have cropped up as a
result. NeoDoc's development includes a
standard in the form of a comprehensive
test suite for use in validating conforming
processors.
-- endnote
NeoDoc isn't a theoretical idea. I've
been using it in production on my site
for years. The fundamentals are solid.
I expect feedback from other folks will
lead to some modifications during a
beta period as more folks use it. But,
I don't foresee anything that would
significantly change its potential.
Work on extracting NeoDoc from my site
generator is underway. I don't have a
specific target date, but it won't be
that long until it's ready for other
folks to start poking at.
-- footnote
-- id: control
It is, of course, possible to migrate
data from one format to another. However,
that's a non-trivial amount of friction
most folks would need someone else to
set up for them (e.g. most folks aren't
going to build their own ETL systems).
-- footnote
-- id: standard
>> Standard.site | https://standard.site/ >>
The shared lexicons for long-form
publishing on AT Protocol.
-- footnote
-- id: jump
I've still got some work to do to get
standard.site connections up and running
for my site. The requirement to verify
every page individually is more work
than I've got time for at the moment.
-- footnote
-- id: manifesto
>>A Vision for the Web |
https://www.alanwsmith.com/en/2v/xa/cn/vj/>>
(originally titled "A Website Manifesto")
is a draft where I kicked around ideas
for a more interconnected web.
Basically, I was trying to figure out
how to build the Atmosphere using
RSS.
-- footnote
-- id: leaflet
>> Leaflet, standard.site, and open
social publishing! |
https://lab.leaflet.pub/3md4qsktbms24 >>
is a great intro to what standard.site is
all about and its integration into leaflet.
-- footnote
-- id: other
>> Automatically syncing your blog to atproto
and standard.site |
https://jola.dev/posts/automatically-syncing-your-blog-atproto-standard-site >>
which mentions the wordpress HTML lexicon.
At least, I think it's referencing a lexicon. I'm
not sure and don't yet know where to look to
figure that out.
-- footnote
-- id: micro
>> Microformats | https://indieweb.org/microformats >>
The >> IndieWeb's | https://indieweb.org/ >>
attempt at standardizing content that never quite
made it.
-- footnote
-- id: md
>> Markdown | https://www.markdownguide.org/ >>
The de facto standard for static site generators
everywhere. Great at what it does, but limited
in what it can achieve.
-- footnote
-- id: mdbook
For example, you could set up a parser to pull the
title from an H2 and then put the author in an H3
with the text for the review below that. That
would work, but it's super brittle and doesn't
provide for expansion without rewriting the
parser and updated all the existing content.
-- footnote
-- id: maybe
Assuming a processor wasn't used to render
this content that transformed the content
to straight HTML.
-- metadata
-- created: 2026-08-03T16:22:00-04:00
-- published: 2026-08-04T16:08:00-04:00
-- id: 01/n7/1y/38
-- tags: neodoc
-- status: done
2 Likes
Welcome! There are a LOT of people with opinions on text formats here 
I have done terrible crimes with YAML frontmatter over the years!
2 Likes
Wonderful write-up. I think alongside this, there should be an effort to establish a common container format that provides a sufficiently extensible structure for metadata such as content format, language, authorship, rights, etc. I personally see MASL as fulfilling this role:
2 Likes
hehehe, yeah. I expect text formats are something you can ask ten people about and get twelve opinions. I guess you could say NeoDoc is the manifestation of mine. I figure I’ve already got the parser so I might as well offer it for consideration.
(At a minimum it’ll be a fun exercise to see if the way I think makes sense to other folks or if it only makes sense to me because I built it. 
)
1 Like