Suitcss doesn't suggest any way to document components.
Therefore README.md and tests are the only places to read about the component and learn how to use and test it, look at some examples etc.
It would be great to have a standard and modular docs system.
Docs should be bound to the package repo/folder.
The docs folder may contain:
(optional) index.md - entry point
[section-name].md - custom docs sections
Sections
Sections are plain Markdown files and are atomic. They are similar to partial templates.
Examples:
overview.md
installation.md
features.md
available-css-classes.md
usage.md
configuration.md
testing.md
contributing.md
browser-support.md
N.B. the filenames are not standard and should not be enforced i.e. one can add as many md files as he/she wants and they will all be available to use.
Entry point
index.md is a reserved section and represents the docs entry point.
It can either be:
Custom made – the doc contains links to each section
Generated – the folder could contain a docs.json with an array of section names which represent the order in the docs. This file can contain other metadata (not sure what yet).
Template – by default generated index.md is a markdown file with links to the sections. Optionally one can provide a template to add presentation.
Compilation
When index.md is in the docs folder an additional compilation step could replace all of the links to the sections with their actual content i.e. inline the sections content.
Examples
Examples are probably the most tricky part because suitcss is only about styling and any example uses hardcoded markup. As consequence of that any generated styleguide may not be live/living.
Examples should live in a subfolder (say examples).
Each example can have an optional *examplename*-readme.md companion which hosts the example description.
In my opinion examples should be plain html files and self contained:
static html
compiled to static html
dynamic templates
web components
react components
If organised like that examples could be reused in tests (or used to automatically generate test pages).
Suitcss doesn't suggest any way to document components. Therefore
README.mdand tests are the only places to read about the component and learn how to use and test it, look at some examples etc.It would be great to have a standard and modular docs system. Docs should be bound to the package repo/folder.
The
docsfolder may contain:Sections
Sections are plain Markdown files and are atomic. They are similar to partial templates. Examples:
N.B. the filenames are not standard and should not be enforced i.e. one can add as many
mdfiles as he/she wants and they will all be available to use.Entry point
index.mdis a reserved section and represents the docs entry point. It can either be:docs.jsonwith an array of section names which represent the order in the docs. This file can contain other metadata (not sure what yet).index.mdis a markdown file with links to the sections. Optionally one can provide a template to add presentation.Compilation
When
index.mdis in thedocsfolder an additional compilation step could replace all of the links to the sections with their actual content i.e. inline the sections content.Examples
Examples are probably the most tricky part because suitcss is only about styling and any example uses hardcoded markup. As consequence of that any generated styleguide may not be live/living.
Examples should live in a subfolder (say
examples). Each example can have an optional*examplename*-readme.mdcompanion which hosts the example description.In my opinion examples should be plain
htmlfiles and self contained:If organised like that examples could be reused in tests (or used to automatically generate test pages).
Feedbacks are welcome