Stylemark

NOTICE: This project has been abandoned. See this issue for details.

Generate interactive style guides from Markdown. Document your style guide components in code comments or Markdown files, and Stylemark will generate a static HTML site with live, interactive components.

Examples

Installation

Requires Node 6.x+

npm install -g stylemark

For a native app with built-in auto-updating/hot-reloading, see Stylemark App.

Documenting style guide components

Documenting style guide components is as easy as writing Markdown. Components can be documented in dedicated Markdown files or as comment blocks within any source code. See the full Stylemark spec.

As a dedicated Markdown file

---
name: Button
category: Components
---

Buttons can be used with `<a>`, `<button>`, and `<input>` elements.

Types of buttons:

-   Default: Standard button
-   Primary: Provides extra visual weight and identifies the primary action in a set of buttons
-   Success: Indicates a successful or positive action

```types.html
<button class="btn btn-default">Default</button>
<button class="btn btn-primary">Primary</button>
<button class="btn btn-success">Success</button>
```

As a comment block within source code

The language of your source code doesn't matter as long as the docs are in /* … */ comments.

/*
---
name: Button
category: Components
---

Buttons can be used with `<a>`, `<button>`, and `<input>` elements.

Types of buttons:
- Default: Standard button
- Primary: Provides extra visual weight and identifies the primary action in a set of buttons
- Success: Indicates a successful or positive action

```types.html
<button class="btn btn-default">Default</button>
<button class="btn btn-primary">Primary</button>
<button class="btn btn-success">Success</button>
```
*/
.btn {
    display: inline-block;
    text-align: center;
    vertical-align: middle;
    …
}
.btn-default {
    …
}

Generating the HTML style guide

In Node.js

stylemark({ input, output, configPath })

Name	Type	Description
`input`	string	Directory where to read from
`output`	string	Directory where to save the generated HTML
`configPath`	string	(optional) Filepath of the stylemark YAML configuration file, defaults to `.stylemark.yml` within the input directory. See Configuration

Example:

stylemark({
    input: "~/git/acme-source-code",
    output: "~/acme-style-guide",
    configPath: "~/acme-source-code/config/stylemark.yml",
})

On the command-line

stylemark -i <input> -o <output> -c <configPath> -w [<delay>] -b [<port>]

Name	Description
`-i`	Directory where to read from
`-o`	Directory where to save the generated HTML
`-c`	(optional) Filepath of the stylemark YAML configuration file, defaults to `.stylemark.yml` within the input directory. See Configuration
`-w`	(optional) Will watch for file changes in `<input>` and rebuild the style guide, waiting at least `<delay>` milliseconds between successive changes (defaults to `2000`)
`-b`	(optional) Will open the style guide in your default browser at `http://localhost:<port>` and will automatically reload it when the style guide is updated. The port will be chosen automatically if not provided.

Example: Build a style guide from path/to/source/code with a custom config file location, and save the generated HTML to path/to/style/guide

stylemark -i path/to/source/code -o path/to/style/guide -c ~/acme-source-code/config/stylemark.yml

Example: Build and open the style guide in a browser, and automatically rebuild and reload it when the source code is modified

stylemark -i path/to/source/code -o path/to/style/guide -w -b

Configuration file

The Stylemark configuration file is a YAML file that contains settings to use when generating the HTML style guide.

NOTE: All paths are relative to root project directory of the configuration file (ie. the first ancestor directory that contains package.json).

name: Name of the style guide

excludeDir: (optional) Regex pattern (in double quotes) or list of directories to exclude; .git and node_modules are always excluded
match: (optional) Regex pattern or list of files to process; by default, common source files are included

assets: (optional) List of relative file/directory paths to copy and mirror in the generated style guide

theme:
    logo: (optional) Filepath or URL of your logo
    css: (optional) List of any CSS files to include in the <head> of the generated styleguide; see Theming section
    js: (optional) List of any JS files to include in the <body> of the generated styleguide; see Theming section
    sidebar:
        background: (optional) Background of the sidebar; any valid CSS background property allowed, but hex colors must be quoted
        textColor: (optional) Text color of the sidebar; any valid CSS color property allowed, but hex colors must be quoted

examples:
    css: (optional) List of any CSS files to include in the <head> of each rendered example
    js: (optional) List of any JS files to include in the <head> of each rendered example
    doctypeTag: (optional) HTML doctype to use for each rendered example; defaults to "<!doctype html>"
    htmlTag: (optional) <html> tag to use for each rendered example; defaults to "<html>"
    bodyTag: (optional) <body> tag to use for each rendered example; defaults to "<body>"
    headHtml: (optional) HTML to insert before the closing </head> tag for each rendered example
    bodyHtml: (optional) HTML template of the example; the example's HTML content will be inserted in place of "{html}"

webpackAppPath: For Webpack apps (esp. React, Angular, etc.), this is the `output.library` value in your webpack config
emberAppName: For Ember apps, this is the name of the Ember app exported to the window object

order: (optional) See Ordering section

Ordering

The relative order of categories can be defined by prefixing a category name with +, -, or nothing:

Categories prefixed with + will be listed first
Categories prefixed with - will be listed last
Unprefixed categories will be listed in between

Omitted categories are ordered as if they were included but unprefixed.

Within each of the +-, --, and un-prefixed groups, the specified order will be preserved. Example:

order:
- +Getting Started
- +Overview
- +Grid
- Topography
- -Extras
- -Other

Theming

The look and feel of the generated styleguide can be customized in the theme section of the config.

For example:

theme:
    css:
    - theme/theme.css

    js:
    - theme/theme.js

    sidebar:
        background: rgb(200, 0, 0)
        textColor: "#fff"

With that configuration, Stylemark will include theme/theme.css and theme/theme.js in the generated styleguide. Note that the background and textColor styles defined in the sidebar section will override any similar styles set in theme/theme.css.

Stylemark includes a number of CSS class hooks you can use to style specific elements. These CSS classes all start with theme- and include:

theme-content: The main scrollable page content
theme-content-category: Set of elements that make up a category
theme-content-element: An element, including its title and documentation
theme-content-element-description: An element's documentation, not including its title
theme-content-element-title: An element's title
theme-content-element-source: An element's source filepath container
theme-content-element-source-label: The text label of an element's source filepath
theme-content-element-source-path: The filepath string of an element's source filepath
theme-mobile-nav: The navigation view visible on smaller viewports
theme-mobile-nav-select: The <select> tag for the navigation dropdown visible on smaller viewports
theme-page: The entire page, including the content and sidebar
theme-sidebar: The sidebar
theme-sidebar-categories: The set of categories in the sidebar
theme-sidebar-category: A category in the sidebar, including its elements
theme-sidebar-category-title: A sidebar category's title
theme-sidebar-element: An element within a sidebar category
theme-sidebar-footer: Sidebar footer
theme-sidebar-header: Sidebar header
theme-sidebar-header-logo: Sidebar header logo
theme-sidebar-header-title: Sidebar header title that contains the styleguide name
theme-sidebar-search: Sidebar search module
theme-sidebar-search-no-results: Text that appears when no sidebar search results are found

IMPORTANT: Use only these theme- classes when customizing your styleguide. Relying on any other internal classes will result in your styles breaking when those internal classes change or are removed.

Example configuration

Here's a sample configuration with all options provided:

name: Acme Design

excludeDir:
    - dist
    - docs

assets:
    - dist
    - fonts

theme:
    logo: assets/brand/logo.png

    css:
        - theme/theme.css

    js:
        - theme/theme.js

    sidebar:
        background: "#3b2a55"
        textColor: "#fff"

examples:
    css:
        - dist/css/app.min.css

    js:
        - https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js
        - dist/js/app.min.js

    doctypeTag: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
    htmlTag: <html id="acme">
    bodyTag: <body class="acme-body">

    headHtml: |
        <meta name="google-site-verification" content="52cae…">
        <script>
            window.disableRouting = true;
        </script>

    bodyHtml: |
        <div style="padding: 20px">
            {html}
        </div>

order:
    - +Introduction
    - +Installation
    - -Credits

mpetrovich/stylemark

mpetrovich

Reviews

Repository Details