Skip to content
This repository has been archived by the owner on Nov 17, 2020. It is now read-only.
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: mpetrovich/stylemark
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: v3.0.3
Choose a base ref
...
head repository: mpetrovich/stylemark
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: main
Choose a head ref

Commits on Dec 16, 2018

  1. Remove rfr node module

    Due to the simple project file hierarchy, node-rfr doesn't add much value and also causes issues such as #59
    mpetrovich committed Dec 16, 2018
    Copy the full SHA
    a352206 View commit details
  2. 3.0.4

    mpetrovich committed Dec 16, 2018
    Copy the full SHA
    bc6bb8d View commit details
  3. Improved baseDir handling within options, so it doesn't go out to the…

    … package.json directory. (#57)
    
    Assets can now be in any location, the baseDir option allows to improve the path of copied assets, especially if assets are not based on root path
    Cyclodex authored and mpetrovich committed Dec 16, 2018
    Copy the full SHA
    25cb268 View commit details
  4. Debounce instead of throttle (#55)

    Cyclodex authored and mpetrovich committed Dec 16, 2018
    Copy the full SHA
    eec7c61 View commit details
  5. Copy the full SHA
    2f5381a View commit details
  6. Copy the full SHA
    6a5a0a1 View commit details
  7. 3.1.0

    mpetrovich committed Dec 16, 2018
    Copy the full SHA
    d96d8b5 View commit details
  8. Copy the full SHA
    357a13a View commit details
  9. 3.1.1

    mpetrovich committed Dec 16, 2018
    Copy the full SHA
    6dc8a29 View commit details
  10. Copy the full SHA
    25f4684 View commit details
  11. Update dependencies

    mpetrovich committed Dec 16, 2018
    Copy the full SHA
    6bf91b3 View commit details
  12. 3.1.2

    mpetrovich committed Dec 16, 2018
    Copy the full SHA
    24b4efe View commit details

Commits on Jan 26, 2019

  1. Fix src/generator.js regex (#61)

    This fixes issue #60
    jussikinnula authored and mpetrovich committed Jan 26, 2019
    Copy the full SHA
    3145bec View commit details
  2. 3.1.3

    mpetrovich committed Jan 26, 2019
    Copy the full SHA
    5524c9b View commit details

Commits on Apr 6, 2020

  1. Add deprecation notice

    mpetrovich committed Apr 6, 2020
    Copy the full SHA
    444c30b View commit details
  2. Update deprecation notice

    mpetrovich committed Apr 6, 2020
    Copy the full SHA
    0b18d75 View commit details
  3. 3.1.4

    mpetrovich committed Apr 6, 2020
    Copy the full SHA
    d19a4ca View commit details

Commits on Apr 22, 2020

  1. Undeprecate Stylemark

    mpetrovich committed Apr 22, 2020
    1
    Copy the full SHA
    3190fb2 View commit details
  2. 3.1.5

    mpetrovich committed Apr 22, 2020
    Copy the full SHA
    8beccdf View commit details

Commits on Apr 30, 2020

  1. 3.1.6

    mpetrovich committed Apr 30, 2020
    Copy the full SHA
    4b4f7e8 View commit details
  2. Update readme

    mpetrovich committed Apr 30, 2020
    Copy the full SHA
    0aac568 View commit details
  3. 3.1.7

    mpetrovich committed Apr 30, 2020
    Copy the full SHA
    9f9a51c View commit details
  4. Remove build files

    mpetrovich committed Apr 30, 2020
    Copy the full SHA
    03710e0 View commit details

Commits on Nov 5, 2020

  1. Add abandonment notice

    mpetrovich authored Nov 5, 2020
    Copy the full SHA
    924c66f View commit details
  2. Copy the full SHA
    c96bdc4 View commit details
Showing with 4,907 additions and 2,622 deletions.
  1. +93 −77 README.md
  2. +4 −4 bin/stylemark
  3. +1 −2 index.js
  4. +4,763 −2,503 package-lock.json
  5. +15 −19 package.json
  6. +14 −0 src/assets/css/theme.css
  7. +5 −5 src/generator.js
  8. +1 −2 src/handlebars.js
  9. +1 −2 src/parser.js
  10. +3 −4 src/stylemark.js
  11. +4 −0 src/templates/doc.handlebars
  12. +2 −2 src/templates/example.handlebars
  13. +1 −2 test/test.js
170 changes: 93 additions & 77 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,34 @@
Stylemark   [![npm version](https://badge.fury.io/js/stylemark.svg)](https://badge.fury.io/js/stylemark) [![Build Status](https://travis-ci.org/nextbigsoundinc/stylemark.svg?branch=master)](https://travis-ci.org/nextbigsoundinc/stylemark)
===
**A living style guide generator for everything.** CSS, LESS, SASS, JS, React, Angular, Ember—you name it.
# Stylemark   [![npm version](https://badge.fury.io/js/stylemark.svg)](https://badge.fury.io/js/stylemark) [![Build Status](https://travis-ci.org/nextbigsoundinc/stylemark.svg?branch=master)](https://travis-ci.org/nextbigsoundinc/stylemark)

Document your style guide components in code comments or Markdown files, and Stylemark will generate a static HTML site with live, interactive components.
**NOTICE: This project has been abandoned.** See [this issue](https://github.com/mpetrovich/stylemark/issues/101) 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.

![Bootstrap style guide](https://user-images.githubusercontent.com/1235062/31162551-2d8f6da6-a8ac-11e7-8874-9e8a2c1c6680.png)

### Examples
- [Bootstrap](http://stylemark-bootstrap.surge.sh/)
- [React](http://stylemark-react.surge.sh/)
- [Ember](http://stylemark-ember.surge.sh/)

- [Bootstrap](http://stylemark-bootstrap.surge.sh/)
- [React](http://stylemark-react.surge.sh/)
- [Ember](http://stylemark-ember.surge.sh/)

## Installation

Installation
---
Requires Node 6.x+

```sh
npm install -g stylemark
```

For a native app with built-in auto-updating/hot-reloading, see [Stylemark App](https://github.com/nextbigsoundinc/stylemark-app).

## Documenting style guide components

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**](README-SPEC.md).

### As a dedicated Markdown file
~~~markdown

````markdown
---
name: Button
category: Components
@@ -36,20 +37,23 @@ 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

- 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.
~~~css

````css
/*
---
name: Button
@@ -78,61 +82,64 @@ Types of buttons:
.btn-default {
}
~~~
````


Generating the HTML style guide
---
## Generating the HTML style guide

### In Node.js

```js
stylemark({ input, output, configPath });
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](#configuration-file)
| 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](#configuration-file) |

Example:

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


### On the command-line

```sh
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](#configuration-file)
`-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.
| 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](#configuration-file) |
| `-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`

```sh
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

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


### Configuration file

The Stylemark configuration file is a [YAML](https://en.wikipedia.org/wiki/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`).

```yaml
name: Name of the style guide

@@ -164,16 +171,18 @@ emberAppName: For Ember apps, this is the name of the Ember app exported to the
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

- 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
@@ -184,11 +193,12 @@ order:
- -Other
```


#### Theming

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

For example:

```
theme:
css:
@@ -201,65 +211,71 @@ theme:
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-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.
- `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:

```yaml
name: Acme Design
excludeDir:
- dist
- docs
- dist
- docs
assets:
- dist
- fonts
- dist
- fonts
theme:
logo: assets/brand/logo.png
css:
- theme/theme.css
- theme/theme.css
js:
- theme/theme.js
- theme/theme.js
sidebar:
background: "#3b2a55"
textColor: "#fff"
examples:
css:
- dist/css/app.min.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
- 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">
@@ -277,7 +293,7 @@ examples:
</div>
order:
- +Introduction
- +Installation
- -Credits
- +Introduction
- +Installation
- -Credits
```
8 changes: 4 additions & 4 deletions bin/stylemark
Original file line number Diff line number Diff line change
@@ -2,13 +2,12 @@

'use strict';

var rfr = require('rfr');
var args = require('yargs').argv;
var chokidar = require('chokidar');
var bs = require('browser-sync').create();
var _ = require('lodash');
var path = require('path');
var stylemark = rfr('src/stylemark');
var stylemark = require('../src/stylemark');

var input = args.i;
var output = args.o;
@@ -18,7 +17,7 @@ var delay = (watch === true) ? 2000 : watch;
var browser = args.b;
var port = _.isNumber(browser) ? browser : null;

var generate = _.throttle(
var generate = _.debounce(
function() {
console.log('Generating style guide...');
stylemark({
@@ -27,7 +26,8 @@ var generate = _.throttle(
configPath: configPath,
});
},
delay
delay,
{ leading: false, trailing: true }
);

generate();
3 changes: 1 addition & 2 deletions index.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
'use strict';

var rfr = require('rfr');
var stylemark = rfr('src/stylemark');
var stylemark = require('./src/stylemark');

module.exports = stylemark;
Loading