-- title

Spoiler/Content-Warning Update

Part of the NeoDoc spec is a list of 
section types that include reference 
HTML templates and rendering expectations 
for output.

Two new section types have been added 
based on the discussion from
>> In Which A Book Lexicon is Born |
https://discourse.atmosphere.community/t/in-which-a-book-lexicon-is-born/1042 >>.

They are: Spoilers and Content Warnings.

There's also a new inline Spoiler tag.
The specific start/stop tokens are TBD, 
but it'll be something like:

  -- pre/

  This is ;;a spoiler;; to
  keep things a surprise.

  -- /pre


-- h2

The NeoDoc Advantage

The Spoiler and Content Warning sections
are prime examples of NeoDoc's ability to 
offer content portability to the Atmosphere.
Without NeoDoc (or something like it) the 
ability to migrate content with spoilers 
or warnings between apps is impractical 
at best.

For example, assuming the use of Markdown,
the two ways that come to mind for 
identifying spoiler and content-warning 
content in plain-text storage are: 


-- numbered/

1. Add custom Markdown tokens like: 

  -- pre/

  ```cw Content Warning Label Goes Here
  Everything in this section is
  behind a content warning.
  ```

  ```spoiler
  This is the content of a spoiler
  section.
  ```

  And ;;this text;; is an inline
  spoiler.

  -- /pre


2. Define specific HTML tag/class 
combinations and roll out to using them.
For example:

  -- pre/

    

      

        Content Warning Label Goes Here
      

      Everything in this section is
      behind a content warning. 

      Markdown parsers should be able 
      to automatically transform these
      blocks into paragraphs.

    


    


      Everything in this section is
      behind a spoiler interface. 

      Markdown parsers should be able 
      to automatically transform these
      blocks into paragraphs.

    


    Here is some
    spoiler text that gets
    hidden.

  -- /pre

-- /numbered


In either case, every app that uses
the content must agree on the syntax/html 
in order to maintain functionality. 

That's a practical impossibility.
There's no realistic way to have portable
spoiler/content-warning content using
Markdown as a result. The same issue 
arises with any other format that doesn't 
have native spoiler or content-warning 
types.

With the feature built in to NeoDoc, 
apps don't have to invent or coordinate
on custom syntax. They simply use
what's already defined in the spec.


-- h2

Change Window

I've been using NeoDoc for three years
in my static site generator. No one else
has it yet. That provides a fantastic 
opportunity to refine its capabilities
to further support the Atmosphere while 
it's being extracted into its own library. 
The spoiler/content-warning is a perfect 
example. I hadn't thought of them
until the topic came up in the community.

What's nice about NeoDoc's format is
that no alterations to the parser are
necessary to accommodate the change. The
only modification is an update to the
spec to include the section types in the 
pre-defined list and supply their 
reference templates. 

A critical point is that these type of
adjustments can only be made before NeoDoc 
is actively in production. Once it is, it'll 
be like a lexicon where stability of the
spec is a requirement. (Further enhancements 
are still possible. They would just have 
to be a matter of community convention
with the possibility of optional addendum 
section type specs, but the parser
functionality won't change.)


-- h2

Outro

I'll end with my refrain: 

Without portable content the full promise 
of a decentralized internet can't be 
achieved. 

While you can move from one PDS to 
another, you're content is still locked 
into specific apps if no one else uses 
the format its stored in. Handling 
multiple formats is, of course, possible. 
But, it would be better spending time
on features that enhance app experience
rather than building ETLs. 

I believe moving content between apps
is more appealing to non-technical users
than being able to migrate their PDS.
While Markdown is portable, it's 
incredibly limited. At the epoch of
the Atmosphere, we should aim for
better. 

-a



-- endnote

Adding the inline spoiler tag __is__ 
a change to the parser. Those changes
are only possible before NeoDoc is
in production. Once the shorthand
tokens have been locked down no
new ones will be added since that
would break backwards compatibility.



-- metadata
-- created: 2026-08-07T07:53:00-04:00
-- published: 2026-08-07T10:16:00-04:00
-- tags: neodoc