Fragments are one of the most important ideas underlying pub-server.
This apparently trivial addition to our Markdown representation, enables "standard" Markdown to be used for ANY page layout. Here's an example:
This works because it allows templates to endow different fragments in a page with their own layout or styles, without resorting to Markdown extensions. The content stays clean.
Fragments are automatically associated with their parent
page when a source is loaded. Templates can then simply target
page.[#fragment-name] or iterate over
Each fragment is an independently-editable piece of Markdown with an identifier which goes all the way back to the source. This is handy for editors.
Notice that fragments may also have their own header metadata. This would be difficult if explicit fragment delimiters were substituted with some convention such as interpreting level-1 Markdown headers as delimiters.
Fragments of anything!
Once you enable multiple Markdown fragments for one page to live in a single file, it becomes obvious that the Markdown for different pages could also live in one file.
Now we have a simple, extensible file format for Web content which includes standards like HTML and CSS, but also includes Markdown, code, and any other type of text content.
"Draft" and "update" fragments
With a little extra metadata, fragments can be marked as
(update), so that one set of source fragments can include published as well as unpublished content.
This is complementary to full-blown git versioning which treats branches as complete sets of files, or simple file versioning (like dropbox or s3) which doesn't maintain any branches at all.
Storing drafts and updates as additional fragments in the same source as the published fragments fits the lightweight approach people are used with wordpress or squarespace, but still allows for staged release management with testing.
A slightly hairy example of all this can be seen in pub-generator/test/single-file-source.md.