neodoc.style

An upcoming lexicon for the AT Proto Atmosphere

Overview

neodoc is a writing format for creating content. It focuses on being easy to use without sacrificing the ability to make full featured posts and pages. If you're familiar with markdown, it's like that, but on steroids.

neodoc.style is an upcoming¹ AT Proto lexicon for publishing neodocs in the Atmosphere. Combined, they provide a new way to publish content for feeds and sites across the Atmosphere and the wider web.

The rest of this page covers the basics. Check it out and hit me up on bluesky if you've got questions.

¹ the neodoc parser already exists. It's embedded in my static site generator and takes care of the roughly three thousand posts on my site. I'm pulling it out to create a stand-alone library for the reference implementation to use for the lexicon.

TL;DR

To give you a quick idea of how it works, this is a neodoc:

-- book-review
-- title: Dungeon Crawler Carl
-- author: Matt Dinniman
-- cover: dungeon-crawler-carl-cover.jpg

First off, I did the audio book instead
of the paper copy. I don't know how much
I would have liked the physical version
but the narrator for the audio book
is absolute gold. 

etc.

it turns into this:

Dungeon Crawler Carl

by Matt Dinniman

First off, I did the audio book instead of the paper copy. I don't know how much I would have liked the physical version but the narrator for the audio book is absolute gold.

etc.

The formatting comes in from the neodoc lexicon. It stores output templates and styles independently from the content. You can created layouts that apply to all your content and versions for individual pieces of content. Or, you can skip them all together and use defaults from wherever your content appears.

Alternate Perspectives

Separating content from layout means different apps can do different things with the same pieces of content. For example, instead of showing a basic timeline, an app could aggregate all the book reviews you've posted on a single page. Something like:

Alan's Book Reviews

Bird by Bird

Some Instructions on Writing and Life

by: Anne Lamott

First off, I did the audio book instead of the paper copy. I don't know how much I would have liked the physical version but the narrator for the audio book is absolute gold.

etc.

Dungeon Crawler Carl

by: Matt Dinniman

First off, I did the audio book instead of the paper copy. I don't know how much I would have liked the physical version but the narrator for the audio book is absolute gold.

etc.

The Buddha Walks into a Bar

A Guide to Life for a New Generation

by: Lodro Rinzler

My therapist thought I'd like this one. She was right.

etc.

The book cover for The Buddha Walks into a Bar

Fool

by: Christopher Mooer

Know what's good about having a fiend you've known since third grade? They give you killer books.

etc.

The Long Way to a Small, Angry Planet

by: Becky Chambers

This was my introduction to Becky Champbers. It was a good one.

etc.

The book cover for The Long Way to a Small, Angry Planet

It doesn't have to be just your books. Apps could just as easily grab all the book reviews from all the folks you follow for the list.

Shorts Included

The book review example shows how to use neodoc for rich content. They can also be dead simple. For example, this is a perfectly acceptable neodoc:

hey you. relax your shoulders.

No fuss. No muss. Just a post similar to one you'd find on Bluesky.

The Format

Sections

Neodocs are made of sections. Each one starts with two dashes and a name. Content for the section follows below it.

-- title

A Neodoc Overview

The section names can be pretty much anything as long as they don't contain spaces.

Section Flags and Attributes

Sections can have metadata attached to them in the form of flags and attributes.

Flags are pieces of text that start with two dashes on the lines below a section name. For example, this is an image section with a flag for the image's filename (the content portion of the section is used for the image's alt text).

-- image 
-- example-image.jpg

The word "example" written in white text 
on a dark read background.

Attributes work the same as flags but start with a keyword followed by a colon. For example, here's a "aside" section with a "class" attribute of "warning":

-- aside 
-- class: warning

There is where you can put something 
that needs extra attention.

Section Types

The content of each section is treated as paragraphs by default. This can be changed by adding a section type after the name. The list type is an example:

-- notes list

- A note about something. 

- Another note about something else.

Another type is checklist:

-- todo checklist 

[] Something that needs to be done

[x] Something that has been done.

Check this out for more info on Section Types

The full list of section types is:

checklist - a collection of items with a status associated with them.
csv - a collection of CSV data.
json - a JSON object.
list - a list that uses bullets for each item.
numbered - a list that uses numbers for each item.
p - paragraph based content.
raw - a raw block of text with no addition processing.

Using a section type for the name of a section works too. For example, creating a generic numbered list is done with:

-- numbered 

1. A note about something. 

2. Another note about something else.

There are also a few section names that are processed as raw instead of paragraphs by default. They are:

css
html
script
math
pre
svg
template
textarea

Spans

Section content can contain spans. They're snippets that wrap text to alter it in some way.

A basic span looks like this:

<<code|console.log()>>

The parts are:

A pair of less than signs (<<) that mark the start of the span.
The type of span (e.g. code in the example above).
A pipe (|) character that separates the span type from the span's content.
The span's content itself.
A pair of greter than signs (>>) that mark the end of the span.

Here's what a span looks like surrounded by more content:

The JavaScript function 
<<code|console.log()>>
prints information to the developer console.

When that content is turned into a web page the span turns into an HTML `<code>` tag like this:

The JavaScript function 
<code>console.log()</code>
prints information to the developer console.

Span Attributes

Spans can have attributes that further enhance their content. They're added by using additional pipes to separate them from the content. For example, a class attribute can be added to the span like this:

<<code|console.log()|class: featured>>

which outputs this HTML:

<code class="featured">console.log()</code>

Multiple attributes can be added by using more pipes. For example, this span (which also shows how spans can be split across lines) adds a `data-language` attribute that can be used to apply syntax highlighting to the code:

<<code
  |console.log()
  |class: featured
  |data-language: javascript>>

The output HTML looks like this:

<code 
  class="featured" 
  data-language="javascript"
  >console.log()</code>

Span Shorthands

There are shorthands for frequenly used span types. For example, backtics denote code spans. The orignal example from above:

<<code
  |console.log()
  |class: featured
  |language: javascript>>

can also be written as:

``console.log()
  |class: featured
  |language: javascript``

Here's some more info on Span Shorthands

The beta testing list of span shorthands is:

``TEXT`` - code span
**TEXT** - bold span
__TEXT__ - emphasis span
~~TEXT~~ - strikethrough span
^^TEXT^^ - footnote
>>TEXT|URL>> - link
[[FILEPATH|alt: ALT_TEXT]] - image span

Next Steps

That's it for the format. There's not much to it. That's largely the point. It pushes to be as minimal as possible without making it harder to make content.

Writing up the details on how the lexicon will work and how content interacts with templates and styles is a work in progress. Same goes for the technical documentation.

I'll be posting updates on bluesky if you want to follow along.

Cheers until next time,

-a