Skip to content
This repository has been archived by the owner on Mar 5, 2024. It is now read-only.

ToIP repo template for mkdocs with ToIP Material Theme to be used as a GitHub Template Repository.

License

Notifications You must be signed in to change notification settings

trustoverip/mkdocs-material

Repository files navigation

Trust over IP - Documentation and Specification Template

This repo is a GitHub Repo Template for creating GitHub repositories within the ToIP GitHub Organization. Newly generated repos will contain all the necessary code for using MkDocs for the development of ToIP Deliverables.

The ToIP MkDocs Material Theme a ready-to-use setup for a ToIP branded version of MkDocs, a static site generator geared towards (technical) project documentation and specification development. The theme is a customized version of Material for MkDocs.

Purpose

This repo has been developed to address the requirements of ToIP Foundation contributors with respect to the authoring process for ToIP Deliverables.

Contributor's Guide

Once the new repo instance has been configured, Documentation and Specification contributors should familiarize themselves with the Contributor's Guide.

Usage

The following instructions pertain to the initial configuration of a new repository instance that has been primed using trustoverip/mkdocs-material GitHub Repo Template.

Prime and clone a new repository

  1. Generate a new repository from this template repository (see GitHub docs).
  2. Clone the new repository (see GitHub docs).

Pick a theme style

This repo supports the use of a Specification styled theme when the ToIP Deliverable Type Indicator is TSS. In all other cases, a General Documentation styled theme is provided.

  1. Open the repository using your favorite IDE (i.e. Visual Studio Code, Atom).
  2. Apply your style selection
Style Configuration Action View Demo
General Documentation Move the mkdocs.spec.yml file, which is located at the root of the repo, to the archive folder. ToIP MkDocs Theme for Documentation
Specification Move the mkdocs.yml file to the archive folder, and rename mkdocs.spec.yml to mkdocs.yml. ToIP MkDocs Theme for Specs

Configure MkDocs

MkDocs uses a YAML file to configure the operational properties for the document generator.

  1. Open the repository using your favorite IDE (i.e. Visual Studio Code, Atom).

  2. Edit the mkdocs.yml file and find the sections depicted below:

    # Project information
    site_name: Trust over IP – General Template
    site_url: https://trustoverip.github.io/mkdocs-material/
    site_author: Jane Doe
    site_description: >-
      Trust over IP Foundation template for general documentation
      and technical specification using Material for MkDocs
    
    # Repository information
    repo_name: trustoverip/mkdocs-material
    repo_url: https://github.com/trustoverip/mkdocs-material
    
    # Content Generator Settings
    docs_dir: 'content'
    site_dir: 'html'
    
  3. Update the following settings:

    1. site_name: Set to ToIP Deliverables name using the naming convention <TypeIndicator><4digitID>: <DeliverableName>. For example, BP000: Utility Selection Criteria.

    2. site_url: Set to the GitHub Pages URL that will serve up this new repo site.

    3. site_author: Set to the sponsoring ToIP WG. For example, ToIP Governance Stack WG.

    4. site_description: Set to a short description of the ToIP Deliverable being documented by this repo.

    5. repo_name: Set using name of the new GitHub repo.

    6. repo_url: Set using the URL of the new GitHub repo.

    7. docs_dir: Enter the preferred directory name for where the content for this document/spec will reside.

    8. site_dir: Enter the preferred directory name for where the static HTML pages will be generated from Markdown files.

    9. extra.title: Set to ToIP Deliverables name using the naming convention <TypeIndicator><4digitID>: <DeliverableName>. For example, BP000: Utility Selection Criteria.

Configure Makefile

  1. Open the repository using your favorite IDE (i.e. Visual Studio Code, Atom).

  2. Edit the Makefile file and find the variables depicted below:

    REPO_NAME ?= mkdocs-material
    UPSTREAM_REPO ?= https://github.com/trustoverip/mkdocs-material.git
    DEV_IMAGE ?= trustoverip/mkdocs-material-devenv
    PANDOCS_IMAGE ?= trustoverip/pandocs-devenv
    DEV_SITE_PORT ?= 7500
    DEV_HOST_DIR ?= host_mkdocs
    PUB_HOST_DIR ?= host_pandocs
    PUBLISH_DIR ?= publish
    
  3. Update the following settings:

    1. REPO_NAME: Provide the GitHub repository name.
    2. UPSTREAM_REPO: Set using the GitHub Repo Clone URL.
    3. DEV_SITE_PORT: Pick a port that will be used for the local test server: https://localhost:8080

Update Readme

  1. Open the repository using your favorite IDE (i.e. Visual Studio Code, Atom).

  2. Based on the type of deliverable that will be associated with this new repo, copy the appropriate template from the templates folder within the trustoverip/deliverables repo to ./archive/SUGGESTED_OUTLINE.md.

  3. Move README.md to the archive folder. Rename it to ORIGINAL_INSTRUCTIONS.md.

  4. Rename DOC_README.md to README.md

  5. Update README.md accordingly.

    1. At the top of your file modify the title so it is in the form:

      <TypeIndicator><4digitID>: Friendly Version of Your Title.
      
    2. Refer to the Contribution Options of the ToIP Deliverables Portal.

About

ToIP repo template for mkdocs with ToIP Material Theme to be used as a GitHub Template Repository.

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published