From 444c30ba2c5258ce0d06fac6e3a02c0b0714faa0 Mon Sep 17 00:00:00 2001 From: Mike Petrovich Date: Mon, 6 Apr 2020 15:11:12 +0200 Subject: [PATCH] Add deprecation notice --- README.md | 171 +++++++++++++++++++++++++++++------------------------- 1 file changed, 93 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index a9da779..c90ea87 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ -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) -=== +# DEPRECATED in favor of [other tools with better support](https://blog.bitsrc.io/6-tools-for-documenting-your-react-components-like-a-pro-5027cdfb40c6). + +# 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. Document your style guide components in code comments or Markdown files, and Stylemark will generate a static HTML site with live, interactive components. @@ -7,27 +9,28 @@ Document your style guide components in code comments or Markdown files, and Sty ![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 +39,23 @@ category: Components Buttons can be used with ``, ` ``` -~~~ +```` ### 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 +84,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 -o -c -w [] -b [] ``` -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 `` and rebuild the style guide, waiting at least `` milliseconds between successive changes (defaults to `2000`) -`-b` | (optional) Will open the style guide in your default browser at `http://localhost:` 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 `` and rebuild the style guide, waiting at least `` milliseconds between successive changes (defaults to `2000`) | +| `-b` | (optional) Will open the style guide in your default browser at `http://localhost:` 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 +173,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 +195,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,56 +213,59 @@ 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-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 `` 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" @@ -258,11 +273,11 @@ theme: 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: htmlTag: @@ -280,7 +295,7 @@ examples: order: -- +Introduction -- +Installation -- -Credits + - +Introduction + - +Installation + - -Credits ```