-- title Introducing NeoDoc Hey folks! I'm Alan, and this is an introduction to NeoDoc. A content format for the Atmosphere^^1^^. -- comment NeoDoc is designed for authoring content that gets turned into web pages and app views. You generally don't publish the untransformed version of a NeoDoc file. But, the app/parser that does the conversions hasn't been wired into this site yet. You're seeing the raw content from behind the scenes as a result. That's not a problem. NeoDoc was designed to reduce the friction of authoring content. A big part of that was making sure it's easy to read in its plain-text state. It's in the spirit of >>Markdown| https://www.markdownguide.org/>>, but way more powerful. For example, when NeoDoc files are transformed into web pages ``-- comment`` sections get hidden. So, this note will automatically disappear when the parser is in place. That's appropriate, since you'll no longer be seeing the raw text at that point. -- h2 How It Started Three years ago, I hit my breaking point with website tools. I was using Next.js^^2^^ and tried to correct a typo. I changed ``teh`` to ``the`` and everything broke. Some random part of the builder simple stopped working. My site is 25 years old. I have no desire to deal with that shit for the next 25. So, I started building my own tools. I took the opportunity to re-examine everything about my setup, including the use of Markdown for content. That inspection did not go well for the format. -- h2 Scratching an Itch One of my favorite truisms is: -- blockquote/ Broken gets fixed. Shoddy is forever. -- /blockquote As great as Markdown is for simple blog posts, it sucks at making interesting pages. Anything beyond basic formatting and you have to roll your own HTML. For the longest time, I considered that a shoddy experience. As I thought about how I want to make content for the rest of my life, I realized it's broken. Or, at a minimum, not the right tool for the job. For what I make, not being able to do interesting things with HTML without having to write the HTML myself is a critical fail. The realization started me down the path of designing a new content format. Something as easy to use as Markdown without sacrificing the power of the web's native language. Three years later, NeoDoc is the result. -- h2 Where It's At The NeoDoc parser is currently embedded in my static site generator. It's fairly well battled tested with the >>three thousand or so pages on the site| https://www.alanwsmith.com/neo-files/report>>. Extracting the parser has been on the todo list forever. It just wasn't a priority. Folks would have to make new tools to use it. Not likely, given the quality of the established website building options. But, you know what doesn't have established options yet? **The Atmosphere**. It's the Wild West. Harkening back to the early days of the web. Before everything was jammed into the conformity of corporate, siloed social networks. It's awesome. -- h2 Taking A Swing We're at an epoch. Standards haven't locked in. Once they have, they'll be insurmountable. Thanks to AT Proto, we don't have to worry about our content being locked away in silos. We can move what we make at our own volition. But, if we're not careful, we'll end up standardizing on Markdown. Or, worse. We'll end up with no standard at all. The theoretical freedom of movement will be lost to the reality of incompatible formats. Apps unintentionally locking us in because no one else is set up process content the way they store it. And so, I'm offering NeoDoc to the Atmosphere. A portable, human readable way to ensure we can move our stuff wherever we want it to go. If that sounds like the kinda thing you're into, you can follow along >>on this site|/>> or >>on Bluesky |https://bsky.app/profile/neodoc.style>>. Until next time, I'll see you in the Atmosphere. ->>a| https://bsky.app/profile/alanwsmith.com>> -- endnote You can check out >>the home page|/>> for more details on the format including some examples that are actually rendered to HTML. -- endnote I'm not the only one thinking about making it easier for different apps to use the same content. The folks behind >>Leaflet|https://leaflet.pub/>>, >>offprint|https://offprint.app/>>, and >>pckt|https://pckt.blog/>> have made >>standard.site|https://standard.site/>>. It's goal: to make content easier to discover, index, and move across the Atmosphere. Hell yeah. Learning about standard.site started me thinking about brining NeoDoc to the Atmosphere. Then, I heard >>an episode of ShotTalk Show| https://shoptalkshow.com/724/>> with >>Dan Abramov| https://bsky.app/profile/danabra.mov>> talking about AT Proto and I had a vision of everything fitting together. Legit __I can see through time / Eureka__ type shit. I've been thinking about it non-stop ever since. -- endnote This is also not the first time I've been thinking big thoughts about the future of the internet. I've got >>an entire manifesto| https://www.alanwsmith.com/en/2v/xa/cn/vj/>> banging ideas around (there was also a whole manic episode, but that's a story for another day). My pondering was around how to use RSS to make connections. The complexities of making that work are out of my scope. I know now that AT Proto is what I was trying to articulate. The good news is that the foundation of AT Proto is set and proven. Now, we can work on content interoperability. I'd love to see NeoDoc fill that roll. I'll be fine if it doesn't as long as __something__ steps up to the challenge. We can't have a truly decentralized internet if we accept vendors locking-in our content, regardless of their motivations. -- endnote NeoDoc is the spec for the plain-text file format. There's more to the overall idea than that. Basically, the project is to create an AT Proto lexicon centered around the format that includes a default set of templates for how to process specific sections and a way to send CSS payloads to style them. Every app that renders HTML with the defaults will produce the same output. For example: -- code/ -- neodoc -- h2 Hello, World! Welcome to the Atmosphere. -- /code will render like this by default: -- code/ -- html <section class="neo-h2"> <h2>Hello, World!</h2> <p>Welcome to the Atmosphere.</p> </section> -- /code Individual accounts can provide a default set of styles for there posts as well as overrides for individual posts. Apps will have a default set of styles that they can use if no user supplied style exists or if they decide to override it. I'm glossing over a ton of details. I'll cover more in future posts. Hopefully you get the gist in the mean time. -- endnote The NeoDoc format includes templating tokens designed to be used with >>MiniJinja| https://docs.rs/minijinja/latest/minijinja/>> (The Rust version of >>Python's Jinja template engine| https://jinja.palletsprojects.com/en/stable/>>). The NeoDoc.style spec includes details on how templating is handled. (The reference implementation will include template rendering out of the box.) There's a bunch more detail there that will come in future posts and as the docs get built out. The key takeaway is that NeoDoc ships with a default set of templates for a selection of section types (e.g. ``-- title``, ``-- h1``, ``-- blockquote``) but anyone can define their own section types and provided the templates to render them. -- endnote I haven't figure out how moderation works in the Atmosphere yet. I've got some ideas but have lots more to learn about it. The full version of NeoDoc.style won't launch until a solid moderation approach is in place. -- endnote Social features are also in the review stage. Being able to like, follow, quote, and reply will all be in the mix. Other features will emerge as progress continues. -- endnote NeoDoc content also works as a free from database. It's maybe my favorite feature. For example, if you have ``-- book-review`` sections spread across your files they can be aggregated into a single page, sorted by date, or author, or rating, or whatever. If a bunch of folks use the same section setup, the can be collected across accounts. You can make the next Good Reads simply by watching the firehose for specific sections. They won't all look the same. Custom styles and templates will ensure things go in different directions. That's a feature. Not a bug. We've lived so long in a world where our content has been defined by database schemes we've forgotten what it's like for things to have a personal touch. NeoDoc brings that back. -- endnote Finally, I'll mention that NeoDoc and NeoDoc.style are non-commercial endeavours. I need to do more research on licensing, but they'll be released under something as open as possible (possibly >>CC0| https://wiki.creativecommons.org/wiki/CC0>>). I'm sure I could get venture capital funding or other sponsorship. I'm actively avoiding that. Unless things go entirely to shit, I'm in a position where I can self-fund the work. That's the direction I'm going. The web was able to become an amazing place because HTML is free for everyone. When >>Tim_Berners-Lee| https://en.wikipedia.org/wiki/Tim_Berners-Lee>> invented the language, he wasn't trying to make money. He created it for sharing. I can't think of a better role model to follow. -- footnote -- id: 1 Well. NeoDoc was originally designed for my static site generator. But, damned if it's not perfect the Atmosphere. -- footnote -- id: 2 Look. I know lots of folks love >>Next|https://nextjs.org/>> and >>React|https://react.dev/>>. They're just way overkill for what I do. The associated complexity causes more issue than I'm willing to deal with. -- metadata -- created: 2026-07-27T19:17:00-04:00 -- published: 2026-08-01T18:22:00-04:00 -- status: done -- tags: NeoDoc