Short Documentation
Short Documentation is an HTML template & documentation project.
The code organization and naming convention allow for a documentation build with minimal
effort. Short Documentation uses
Pug, SCSS, and TypeScript, and uses a
configuration file to jump start project development (by building out all the files and
folders as defined in the JSON file).
Here's all the example links in case you wanted to skip the documentation below.
Sample Project Templates:
Sample Documentation:
Table of Contents
Installation
Install Yeoman and the Short Documentation generator.
$ npm install -g yo # install yeoman globally;
$ npm install -g generator-short-documentation # install the short-documentation generator globally;
Yeoman Generator
Configuration
The Short Documentation generator uses
config-yeoman.json to do the inital build out of the project. This
JSON file should save you significant time at the beginning of each
project by creating most of the files and folders you need, and linking them together.
See the comments in the code block below for how to build the configuration file.
{
"project": {
"name": "my project name" // name your project, this shows up in the readme;
},
"components": { // create an entry for each project component;
"header": { // the key is the folder name for this component;
"js": true // if ‘js’ is true, create a JS file for this component;
},
"nav": {}, // a JS file will not be generated for this component;
"promo": {
"js": true
},
"footer": {}
},
"templates": { // create an entry for each template in this project;
"home": [ // the key is the folder name for this template;
"header", // array of all the component used in this template;
"nav",
"footer"
],
"article": [
"page-header",
"nav",
"promo",
"page-footer"
]
}
}
Run Generator
Navigate to your project folder (that contains
config-yeoman.json).
$ yo short-documentation # project files and folders are created;
Congratulations, your Short Documentation project has been built. Below is a link to the project looks after the generator has run:
Short Documentation
Here is an example of how the Short Documentation project looks after all the components and templates have been styled for a mock ACME company website:
Thank you acmelogos.com for the logo.
Install Dependencies
$ npm install -g typescript # install global dependencies
$ npm install # install local dependencies (and types)
Scripts
$ npm start # build the project
$ npm start server # build the project with a web server, and a watcher
$ npm start docs # build the project with documentation
$ npm start server docs # build the project with documentation, a web server, and a watcher
Configuration
Short Documentation parses the components and templates folders looking for
README.md files. When a README.md file is found, that
component or template are included in the documentation app. The
README.md is not just a markdown file, it contains some YAML at the top
to configure the display of the component or template.
The YAML and Markdown are separated by Node. The YAML is used to configure the documentation navigation and page, the Markdown is content on the documentation page.
Component README.md
---
nav: Primary Navigation
icons: bars bolt
size: 100%
pug: nav-primary.pug
ts: nav-primary.ts
views:
- title: Primary Navigation (Home page)
json: nav-primary--home.json
- title: Primary Navigation (Article pages)
json: nav-primary--article.json
---
# Primary Navigation
Interactively procrastinate high-payoff content without backward-compatible data. Quickly cultivate optimal processes and tactical architectures. Completely iterate covalent strategic theme areas via accurate e-markets.
Globally incubate standards compliant channels before scalable benefits. Quickly disseminate superior deliverables whereas web-enabled applications. Quickly drive clicks-and-mortar catalysts for change before vertical architectures.
Credibly reintermediate backend ideas for cross-platform models. Continually reintermediate integrated processes through technically sound intellectual capital. Holistically foster superior methodologies without market-driven best practices.
Component YAML
nav: Component Title # used in the documentation navigation;
icons: bars bolt # optional. space-delimited list of FontAwesome icons to add in the documentation navigation;
size: 350px # optional. default is 100%; CSS width value to apply to the container around the component;
pug: component.pug # filename of the component Pug file;
ts: component.ts # optional. filename of the component TypeScript file;
views: # list of component views to display (multiple are allowed);
- title: Component Title (variant) # title of this view;
json: component.json # JSON data used to render this view;
Template README.md
---
nav: Article Pages
icons: file-text-o
pages:
- title: Privacy Policy
url: /article--privacy-policy.html
- title: Terms of Use
url: /article--terms-of-use.html
- title: Movie Review
url: /article--movie-review.html
---
# Article Pages
Interactively procrastinate high-payoff content without backward-compatible data. Quickly cultivate optimal processes and tactical architectures. Completely iterate covalent strategic theme areas via accurate e-markets.
Globally incubate standards compliant channels before scalable benefits. Quickly disseminate superior deliverables whereas web-enabled applications. Quickly drive clicks-and-mortar catalysts for change before vertical architectures.
Credibly reintermediate backend ideas for cross-platform models. Continually reintermediate integrated processes through technically sound intellectual capital. Holistically foster superior methodologies without market-driven best practices.
Template YAML
nav: Template Title # used in the documentation navigation;
icons: file-text-o # optional. space-delimited list of FontAwesome icons to add in the documentation navigation;
pages: # list of template pages to display (multiple are allowed);
- title: Template Title (variant) # title of this page;
json: template.json # JSON data used to render this page;