Welcome To Neopolitan

Introduction

My site is twenty years old. Thinking back on the past two decades got me thinking forward to the next two. Instead of, "What do I want to use for my next redesign?" I'm asking, "What foundation do I want for the next twenty years?"

The answers are very different.

The Format

I've moved my site a half dozen times. Each one involved a painful content migration. I've gone from raw HTML to Perl to Wordpress to PHP to Ruby to Markdown to MDX to Org-Mode to a mix of all of the above.

The prospect of using any of those formats for the next twenty years is pretty unappealing. So, I designed a new one. It's called Neopolitan and it looks like this:

-> title

Welcome To Neopolitan

-> subtitle

A plain-text format for websites

-> note
>> title: A Quick Heads-Up

I'm doing the "launch before you're ready - build in 
public" thing. The ideas for the format are in place. 
The example implementation I'm building is still a work 
in progress.

-> h2

Introduction

My site is twenty years old. Thinking back on the past
two decades got me thinking forward to the next two. 
Instead of, "What do I want to use for my next redesign?" 
I'm asking, "What foundation do I want for the next twenty 
years?"

The answers are very different.


-> attributes
>> date: 2023-04-16 19:06:40
>> type: default 
>> status: published

How It Works

Documents are made of two things:

1. Sections which start like this: ->

2. Attributes which start like this: >>

The Sections

Sections are things like:

-> title

-> h2

-> list

-> table

The section types determine how content is treated. For example, the -> h2 sections turn into <h2> elements,

-> h2

Bring your best compass 

<h2>Bring your best compass </h2>

A list of content sections with examples is here

The Attributes

Attributes are where things get interesting. They get transposed directly into the HTML.

Here's the same -> h2 example from above with an id and class added.

-> h2
>> id: alfa
>> class: bravo

Bring your best compass 

<h2 id="alfa" class="bravo">Bring your best compass </h2>

Attributes aren't restricted to the HTML output. They can be used as metadata for the processing engine or to add supplemental content.

For example, I use a title attribute to add a header to my code blocks. This:

-> code
>> title: Foxtrot Example Title

alfa bravo charlie

Renders this:

alfa bravo charlie

Inline Tags And Attributes

Content markup is done with inline tags. They start with two `<<`` characters and end with a closing `>>`` pair.

Open <<your|strong>> book

Open <strong>your</strong> book

Attributes can be added by appending them with pipe separators. Here's what that looks like:

Open <<your|strong|id:delta>> book

Open <strong id="delta">your</strong> book

Multiple attributes are separated with the pipe character:

Open <<your|strong|id:delta|class:echo>> book

Open <strong id="delta" class="echo">your</strong> book

The list of inline tags is here

Shorthand Tags

There are shorthand features as well. Here's the strong version:

The *first** draft

The <strong>first</strong> draft

Attributes are added like this:

The *first*class:tango* draft

The <strong class="tango">first</strong> draft

Multiple attributes are separated by pipe characters.

The *first*id:alfa|class:bravo* draft

The <strong id="alfa" class="bravo">first</strong> draft

The Metadata Sections

Some sections don't output directly. They're used for metadata that can be placed on the page independently or used during processing.

For example, I use the attributes section to hold the date and identify the template to use via a type attribute.

-> attributes
>> date: 2023-04-16
>> type: default 
>> status: published

The list of metadata sections is here

The Functional Sections

The third section type is for heavier processing. Sections for -> css and -> script copy their contents directly to head of the document.

The -> ext section calls out to an external process and outputs its contents directly.

The list of functional sections is here

The Engine

I'm not a particular fan of the term "dogfooding". "Drink your own champagne" is worse. Either way, that's what I'm doing. This site is built from the Neopolitan documents and a site generator I'm putting together to use them.

The site generator is relatively generic. It parses documents into an internal AST then uses templates to output the content. I'm really happy with where it's headed, but it's not something I'm going to turn into a supported project. It's goal is to build my site.

That said, I think the format itself might be of broader interest. I write a good bit and I've been very pleased with what I can do without having to jump into a coding session. Content level attributes and metadata are even more powerful than I thought.

If you're interested in playing with the format the engine can show you how I set up the parsing. The repo is here . Feel free to hack on it as much as you'd like.

- alan