SAFETAG Toolkit

Getting Started Guide

About this presentation

This presentation is also available as a markdown guide and we welcome contributions!

You can view a commented video of this presentation at:

• https://…
  

Edit

Atom

pandoc conf in markdown enhanced preview: markdown_github+yaml_metadata_block+definition_lists+markdown_in_html_blocks+grid_tables

Syntax

Refer to a Markdown manual for the basics of the syntax.

There is some special syntax.

Transclusion

Transclusion is a way to reference content snippets (or more) into a document.

• index.md

  Hi :[](name)!

• name.md

  Alice

Will be rendered as:

Hi Alice!

This helps make content more reusable since the snippet’s content can be transcluded several times and updating the snippet will automatically update all the locations where it is transcluded.

We say that the “content” is “dependent” on the transcluded “content”.

:[title](link) this will include the link snippet content in the current document.

In the easiest case, link is the name of a file in the same directory, but it can also be used with the following type of links:

Smart links

Smart links are easy to write and should “do the right thing” so you can focus on your content. The link resolution mechanism is described in more details below. It follows the general principles:

• Concise: Avoiding writing extensions
• Modular: The should support reusable content packages.
• Adaptable: They should not need to be changes when overriding content (See Overrides)
• **
  

In more details:

• :[](name) - This will match the first of the following cases:
• in the same folder as the content.
  • a file called name and will transclude it.
  • a file called name.md and will transclude it.
  • a folder called name with an index file and will transclude it.
  • a folder called name with an index.md file and will transclude it.
  • a folder called name with no index, it will transclude all files in the folder.
• the same in the parent folders all the way to the workspace’s root.
• content packages
  • a content package called name installed in the content repository.
• :[](folder/name)
• same as above
• content packages
  • a content package called folder with a subpackage name, the subpackage can be:
  • a file called name, name.md
  • a folder called name with and index or index.md file
  • a folder called name with no index and it will transclude all files in the folder.
    

Explicit links

• :[](name.md) this will only match a file called name.md in the same directory and will transclude it.
• :[](./folder/name.md) this will only match a file in the folder subdirectory of the content’s directory.
  

Overrides

Overrides allow to modify published content with your personal customisation with minimum changes and making it easy to later contribute back these changes to the publication.

Overrides are enabled by workspaces. A workspace is a dynamic representation of the content which is kept connected to its source publication (allowing updates and making it easier to contribute back), but which is optimised for content authoring (hiding technical details about rendering), content editing (SOON - with version control and collaborative features).

Here’s a basic override example:

   .
   ├── index.md          // Index
   └── :chapters/        // `:` means that the chapters are from a content package.
       ├── chapter_1.md  // as a consequence these chapters are linked
       └── chapter_2.md  // and should not be modified.

In order to override it with your own chapter 2, you need to :

• create a chapters folder in your workspace
• create a chapter_2.md file in this folder.
  

This is what it will look like:

   .
   ├── index.md            // Index
   ├── chapters/           // This new folder will setup an override.
   │   └── chapter_2.md    // This will override chapter_2.md
   └── :chapters/          //
       ├── chapter_1.md    //
       └── chapter_2.md    // This is now masked.

This makes it easy to start working on your own versions of content without having to worry about making irreversible changes. This is also setup (SOON) to deal with version control for you so that every change is properly tracked and facilitate content packaging so that it’s easy to contribute back.