SOIL uses semantic versioning. Changes can be tracked from the GitHub commit history.

Version: v0.11.0

Currently the SOIL standard is in experimental, exploration state. The goal is to finalize the initial version of the standard by January 2019.

After version 1 of SOIL all subsequent versions are guaranteed to be 100% compatible with the initial version to ensure maximum sustainability and compatibility.


The following are required for any SOIL module:


Plugins, extensions, and such will be created first for these best-of-breed tools and services:


The SOIL standard assumes a trusted learning environment defined as follows:

  • Learners trust facilitators to guide their learning;
  • Facilitators trust learners to learn;
  • Learners take responsibility for their learning;
  • Learners pledge to not cheat themselves or others;
  • Learners pledge to make violations known;
  • Assessments are designed for the individual;
  • Assessments provide immediate results and feedback;
  • Assessments need not be secured;
  • Advancement is based on projects and participation.

This code of trust has been an essential part of human self-driven education since humans started learning.

This trust enables interactive assessments to be placed inline with the content itself, removes the dependency on secure assessment results storage, and simplifies everything as learners are trusted instead of feared for how they will defeat the assessment.

💬 We recognize that such trust is hard to find in many organizations today. This is unfortunately not something within SOIL's scope to correct. We can only create a standard assuming this best possible learning environment thereby, hopefully, promoting the growth of such environments.


The SOIL standard requires all content be created for the individual doing the learning and no other reason. Specifically, interactive systems of assessment, which must be secondary, do not need to be secured in any way. This allows them to be easier to implement and included throughout the content.


The Web is the most ubiquitous of technologies and allows rich interactive learning content. SOIL modules can therefore leverage the web platform to the fullest.


Often a parent SOIL module will be composed of other modules but have its own domain or subdomain. This is why it is important that module content always refer to local sections by slug heading or provide the full URL when linking out even if the link points to another module on the same domain.

💬 This avoids the problems that creep up related to local web addresses in most rendering systems.


💬 No module ever really needs more than 50mb.

For many years the storage allowed to an app has been 50mb. This has changed and completely depends on how and where the SOIL content is being rendered and read.

Therefore, there is no formal limit on storage size only the caution to remember your audience and error on the side of caution.


In order to simplify content creation, keep it current, and maximize compatibility, only evergreen browsers are supported. Evergreen browsers are those that are automatically upgraded to current and future versions.


BaseML is the only language any author must learn to write a SOIL module. Simplicity of authoring is a core tenet of SOIL philosophy. Although SOIL leverages the best practices and tools of programmers, SOIL content creators are not expected to be programmers.

BaseML is simple enough to keep the primary written content compatible with all Markdown tools and formats while allowing the inclusion of interactive secondary content coded in HTML, CSS, and JavaScript such as VuePress components.


SOIL module content must be styled in such a way that a high-contrast presentation of the content is easily possible. This supports those with color and other visual difficulties. Specifically this includes:

  • Underlining for hyper-links
  • Prefer serif fonts for main body
  • Black on white main content (allows easy inverting)
  • Zero dependency on color alone

💬 One test of your styles is simply to set your monitor to black and white (grayscale) and see if you can distinguish all the important elements of your content.


Technical writers can and should add secondary programmed interactivity into their documents requiring additional languages—notably HTML, CSS, and modern JavaScript.

However, this programmed interactivity must always be secondary to the written content itself. When evaluating additional interactive content one should ask, "Could the content stand alone without this interactive component?"


Images must be locally sourced (no src=https...).

Images are restricted to JPEG, PNG, and GIF raster (pixel) formats by BaseML with specific size and dimensions for best display inline with written content.

Remember that when possible images should always be secondary to written content.

💬 Higher resolution images can still be included in the SOIL module but must be linked instead of included in the page.

⚠️ Although animated GIFs are supported consider replacing them with MP4 video instead which is now fully supported and unfettered by license restrictions. The quality and size of MP4 video will always be better.


Externally linking to video is common and encouraged.

However, it is often preferable to include the video with the SOIL module itself to keep it modular. Modern renderers and the progressive web app approach do not place restrictions on the amount of video content. This has the added benefit of removing a dependency on the Internet in the true offline first sense.

Video is limited to MP4 format, which is free of any license or other limitation.

Remember that when possible images should always be secondary to written content.

⚠️ Make sure you warn users of your SOIL module if you make heavy use of video which may surpass their bandwidth limits.


Remember that when possible audio should always be secondary to written content.

Audio is limited to MP3 format, which is free of any license or other limitation.


Every SOIL module must be contained in a Git repository.

💬 The SOIL logo is a play on the Git logo itself.

In most ways knowledge source content is no different than source code. It follows, then, that it stands to gain all the same benefits from source code management including the world's leading source management system, Git.

💬 Git has clearly become the established technology for storying source code. Billions of lines of source code now depend on it to be kept safe.

  • GitHub is the world's largest software repository with 27 million users which Microsoft purchased for 7.5 billion dollars in 2018. Private repos are free for students. Organizations can purchase a business service that requires access to their system.

  • GitLab allows free private repos, is based on open source containers, and can be installed locally within an organization for free with service plans available for purchase.

  • BitBucket allows private repos and can also be setup within an organization for a subscription fee.

  • A personal git repo hosted and managed individually can be kept anywhere. Organizations can setup central servers to host these and simply create new repos for each project on the server.


Multiple SOIL modules can be contained in a single Git repository much like a single repository may contain several libraries and modules within a single software package. Each directory within the repository has the potential to be a SOIL module if a file is found.

Local and external content that is linked from a module is logically assumed to be a part of the parent module linking to the content whether or not that content is local or remote. Links can be tracked by SOIL module registries and crawlers and those that are SOIL modules themselves called out visually as a distinction.


Modules should not link to any content that it does not depend on. Either the linked content is considered a part of the module or a prerequisite for it.

⚠️ Do not link to content considered next in order but not immediately a part of the current module. These are not dependencies. Instead create parent modules that link to this content directly.

Maintaining this idea of dependency is crucial to auditing content for updates over time through automated dependency graphs or by hand.

💬 Dependency graphing tools can easily spot broken links and content that has been updated since the dependency graph was last made. This is the core architecture of tools like npm, yarn, apt, rpm and other package managers from the software world.


Git repositories that contain SOIL module knowledge source must use the /docs directory in which to store the source. This is to prevent conflict with other source code, meta files, and assets that might be useful to store at the top level of the directory.

💬 This convention has been used for years by thousands of software development projects and allows a clean separation between the documentation and the thing being documented. It allows other directories like /app and /build to exist as peers without conflict.

💬 Although this is an English word, this convention has been carried to all languages.

The file has been a conventional file to hold documentation about software projects for several years. This convention is at the heart of the VuePress architecture and others.

Every SOIL module is contained in a directory, called a "folder" by some. Within the directory is the required file. Other files can be included and linked from the main file, but it is the entry point to the module.


💬 Although this is an English word, this convention has been carried to all languages.

The LICENSE file is another long standing convention for including the license under which the content is released. All SOIL modules must be released under a creative commons license. See creative commons for options.

You might like to additionally post the copyright to the main page if it is separate from the module itself.


This line contains a reference note[¹](/refs/#_1).

It's important to distinguish between notes and references. Notes are superscript arabic numerals available in UNICODE with emojis. Notes that refer to references should link directly to a section of the references page.

⚠️ There is no need to surround the note with brackets in the content itself (as seen on Wikipedia) because the content of the section for the note on the reference page can changed instead.

⚠️ Do not use any of the available Markdown extensions for superscript since they are not compatible across all Markdown engines and simply not needed.

Notes that link to other available resources on the web are simply not needed. This was the major motivation behind the creation of the Web in the first place. Simply link to the material directly and the external nature of the link can be automatically summarized by analyzers.

Consider a block for parenthetical annotations and other note-like content.


If a traditional reference is required for citations and such simply create a note in the content and directly link it to a section heading on a separate references page (usually in /refs/

The references themselves should be consolidated onto their own separate page with each number having its own heading. This allows note numbers to prominently and reliably be linked from anything.

If the note points to a specific location in a bibliographic reference then provide the specific information under the heading and create an additional section named References (or whatever other name depending on the language). Then locally link from the specific note section on the same page to the References section (as is common on Wikipedia).

Last Updated: 10/22/2018, 12:23:13 AM