Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/oddbird/sassdoc-theme-herman
An Odd SassDoc theme.
https://github.com/oddbird/sassdoc-theme-herman
Last synced: about 17 hours ago
JSON representation
An Odd SassDoc theme.
- Host: GitHub
- URL: https://github.com/oddbird/sassdoc-theme-herman
- Owner: oddbird
- License: mit
- Created: 2015-11-18T19:13:56.000Z (almost 9 years ago)
- Default Branch: main
- Last Pushed: 2024-10-25T18:15:10.000Z (20 days ago)
- Last Synced: 2024-10-29T18:48:53.303Z (16 days ago)
- Language: JavaScript
- Homepage: http://oddbird.net/herman/
- Size: 329 MB
- Stars: 117
- Watchers: 7
- Forks: 11
- Open Issues: 39
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# [Herman][herman] [a [SassDoc][sassdoc] theme]
[](https://github.com/oddbird/sassdoc-theme-herman/actions/workflows/test.yml)
> **If it's not documented, it doesn't exist.**
> Documentation should become the default --
> an integrated part of the development process.
>
> ---Miriam Suzanne
At [OddBird][oddbird],
we wanted better tools for documenting
the entire front end of a project --
from brand guidelines to UX patterns and code APIs:
- Documenting the intersection of languages and styles
- Written directly in the code,
and integrated with code architecture
- Automated for a document that grows and changes
along with the life of your project
Herman is built as an extension to [SassDoc][sassdoc],
and supports all their core functionality
with additional support for
[font specimens][font-docs], [color palettes][color-preview],
[sizes and ratios][size-preview], [SVG icons][icon-docs],
[compiled languages][example-docs], Nunjucks/Jinja macros, HTML previews,
and more.
[font-docs]: https://www.oddbird.net/herman/docs/demo_fonts
[color-preview]: https://www.oddbird.net/herman/docs/demo_colors
[size-preview]: https://www.oddbird.net/herman/docs/demo_sizes
[icon-docs]: https://www.oddbird.net/herman/docs/demo_icons
[example-docs]: https://www.oddbird.net/herman/docs/demo_examples
## Getting Started
```bash
npm install sassdoc sassdoc-theme-herman
```
Note: Dart Sass (`sass`)
is required to use Herman
to display samples of Sass/Scss code.
If it's not already installed in your project,
install it along with Herman:
```bash
npm install sass
```
See the [SassDoc documentation](http://sassdoc.com/getting-started/)
to run SassDoc via various build tools.
Specify `herman` as the theme
in your SassDoc options:
```bash
sassdoc --theme herman
```
### SassDoc Comments
Currently,
all SassDoc/Herman annotations are written as Sass comments
starting with `///` to differentiate documentation
from other developer comments (`//`).
```scss
// This comment will be ignored by Herman
/// This comment will be rendered in the documentation
```
Annotation comments can be free-floating,
or attached to a particular Sass/CSS object --
such as a variable, mixin, function, or selector block.
Note that while SassDoc allows annotation comments
to be separated from the documented code by newlines,
Herman considers documentation to be free-floating "prose" if
it is separated from documented code by one or more newlines.
```scss
/// this is a free-floating comment
/// this comment is attached to the following mixin code-block
@mixin sample-object { … }
```
### Herman Annotations
In addition to the core SassDoc annotations,
our [`@icons` annotation][icon-docs] allows you to
display SVG icons from a given folder,
and we extend the core [`@example` annotation][example-docs]
to display compiled Sass/Nunjucks output
and render sample components.
We also provide a [`@font` annotation][font-docs]
for displaying font-specimens,
and `@colors`, `@sizes`, and `@ratios` annotations
for displaying [color-palettes][color-preview],
[text and spacing sizes, and modular ratios][size-preview].
[herman]: https://www.oddbird.net/herman/
[oddbird]: https://www.oddbird.net/
[sassdoc]: http://sassdoc.com/
[See the full documentation for details »][docs]
[docs]: https://www.oddbird.net/herman/docs/configuration
## SassDoc Extras
Herman uses a number of SassDoc Extras:
- [Description](http://sassdoc.com/extra-tools/#description-description-descriptionpath)
- [Display](http://sassdoc.com/extra-tools/#display-toggle-display)
- [GroupName](http://sassdoc.com/extra-tools/#groups-aliases-groupname)
- [ShortcutIcon](http://sassdoc.com/extra-tools/#shortcut-icon-shortcuticon)
- [Sort](http://sassdoc.com/extra-tools/#sort-sort)
- [ResolveVariables](http://sassdoc.com/extra-tools/#resolved-variables-resolvevariables)