SpinSpire Training Content

This is the source repo for training content produced by SpinSpire team. The course material is intended to be consumed by trainees/students from a static site generated from this content.

It uses the follwing:

• markdown (*.md) is the source format, which is a text-like format that gets converted to HTML files during build
• 11ty is the static site generator
• Nunjucks templating language is used for layouts and sometimes NJK is included in the markdown files themselves (although that should be minimized)
• Bootstrap is the CSS framework to make the HTML look pretty

Setup

We use pnpm instead of npm for package management, so please install it using npm install -g pnpm.

git clone url-of-this-repo
cd training-content
pnpm install
pnpm start #live development: runs watch and serves site
pnpm run build #compile for deployment

How to write content

• Create/update modules in *.md files in src directory
  • Use VS Code and it's "Markdown All in One" extension
  • Run the pnpm dev live server above to see changes in real-time
  • You could also use the Ctr-Shift-V or Cmd-Shift-V to preview markdown rendering within VS Code
• Add the category field in front-matter
• If you invent new category then don't forget to also add it to index.md front-matter categories field
• Use weight field to control the order of modules within a category
• Use references as appropriate
• In general, make sure you review the existing modules, and follow the existing style in both content and code

See the Authoring Guide for the style and structure of the content.

How to code (for Static Site Generation)

• src
  • index.md: home page
  • _includes/default.njk: default layout, edit this for most HTML changes outside the markdown
• .eleventy.js: 11ty configuration
• package.json: You know what this does. If not, don't touch.
• pnpm-lock.yaml: This is generated by pnpm install. Don't edit by hand, but do commit if it changes.
• docker-* and .env.example: Docker related. Advanced uses only.
  • If you want to run under Docker, then copy .env.example to .env and edit it before use.