Write Guidelines for Markdown structure

[iilab]

Write Guidelines for Markdown structure

[seamustuohy]

Check out http://archieml.org: a structured text format optimized for human writability.

[poser]

Nice. Purpose built and oh so minimal. Archieml is definitely plucking at my heartstrings...

On the other end of the "mediated experience" continuum, Carol stumbled upon PubPub last week. At the moment, it's heavily optimized for traditional documents, but it seems to have a lot going for it. Think collaborative, Markdown-based medium.com. It's supposed to be "open sourced within the month" but the developer seems quite responsive.

And those includes (e.g. [[image: source=2falogopng, align=left, size=small, caption="FreeOTP"]]) might be enough to accommodate a lot of non-text structures we need for guides, curricula, apps, etc. Assuming they are extensible. And assuming this thing is built on top of git.

Anyway, my username is 'poser' and Carol's is 'Cee Dub'. We can add you as collaborators if you track us down. I added an orphaned, half-written Security in-a-Box guide for testing and Carol added something from LevelUp.

[jmatsushita]

Good chatting earlier about structure @poser

Here's few things that came up and could be of interest for similar use cases for re-usable bits of content (snippets) being included (transcluded) into documents.

The specific use case here was to have the same document (let's call it the master document), contextualised with different snippets. In that case:

• It would make sense for the snippets to live close to where they are used.
• Snippets link in the master document could be relative to pick up the contextualised snippets.

A few things I've added with regards to linking:

• a snippets folder ([[snippet_01]] ==> [[snippets/01]] which I think is
• descriptive names for snippets ([[snippets/01]] ==> [[snippets/story]]).

en/
  master/
    a_guide/
      index.md              # The master document with relative includes such as [[snippets/story]]
      snippets/
        story.md
        example.md
  another_context/
    a_guide/
      index.md              # Just the metadata pointing to en/master/a_guide/index.md
      snippets/
        story.md            # The story contextualised to another_context
        example.md      # The example contextualised to another_context

I've added PubPub in the discussion on editors #5 and I'll muse about transclusion in #12 and maybe will create a new issue about which ways to extend what.

@elationfoundation I had seen ArchieML before and did really like the more resistant white-spacing aspect and generally resilient approach! Definitely to add on the list of supported metadata formats for contentascode (I've created an issue for that #29) !

[jmatsushita]

After looking at a few, I prefer the Hercules Markdown transclusion syntax which is :[text](file.md)

But here are a few for reference:

• MultiMarkdown {{some_other_file.txt}} http://fletcher.github.io/MultiMarkdown-4/transclusion jgm/pandoc#81
• Marked2 <<[sections/section1.md] http://marked2app.com/help/Multi-File_Documents.html http://marked2app.com/help/Special_Syntax.html#fileincludes
• LeanPub <<[Code title](folder/filename) https://leanpub.com/help/manual#leanpub-auto-code-samples

What I like about I like about :[text](file.md):

• It's more terse than the alternatives above.
• It looks more like Markdown
• It degrades well as most parsers will treat it like a basic link.

In addition the format used by Hercules https://github.com/jamesramsay/hercule which is also including things like providing context :[Required Ingredient](cucmber.mson required:"required") and seems well tested and maintained, and aimed also at API Blueprint which has pretty strong integrity needs. Plus we can probably use the library to deal with assembly.

[seamustuohy]

Have you checked out restructuredText. I just started playing with it on a project and then watched this video and think it might have built in a lot of the internal metadata and semantic structure that is required in your comments. https://www.youtube.com/watch?v=eWNiwMwMcr4