From 5c3327b950a6c313223f606257a22c33a8333f51 Mon Sep 17 00:00:00 2001 From: Mike Petrovich Date: Tue, 25 Feb 2020 15:00:34 +0100 Subject: [PATCH] Update readme --- README.md | 58 ++++++++++++----------------- bin/cli.js | 3 +- docs/examples/stylemark.config.json | 5 +++ src/stylemark.js | 9 ++--- 4 files changed, 34 insertions(+), 41 deletions(-) create mode 100644 docs/examples/stylemark.config.json diff --git a/README.md b/README.md index 3986e6f..d274ee6 100644 --- a/README.md +++ b/README.md @@ -17,26 +17,20 @@ Stylemark requires Node.js v8+ npm install stylemark ``` -Install the appropriate addons if your components use any of these UI frameworks: - -```sh -npm install stylemark-react -npm install stylemark-vue -npm install stylemark-angular -npm install stylemark-ember -``` - ## Usage -### Command-line +### Command-line interface (CLI) ```sh -npx stylemark +npx stylemark [-w|--watch] ``` -`` can refer to a JS or JSON file. +| Parameter | Description | +| --------------- | ---------------------------------------------------------------------------------------------------------- | +| `` | JS or JSON file containing a configuration object | +| `-w`, `--watch` | Opens the generated styleguide in a browser and reloads when any matching input files are added or changed | -### Node.js +### Node.js API ```js const stylemark = require("stylemark") @@ -44,36 +38,32 @@ const stylemark = require("stylemark") stylemark(config) ``` -`config` is a configuration object as described below. - ## Configuration -Stylemark can be configured with a JS or JSON file. +| Property | Type | Default | Description | +| -------- | -------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------- | +| `input` | string or array of strings | | Input path globs. See [Globbing patterns](#globbing-patterns). | +| `output` | string | | Output directory path. Directories will be automatically created if they don't exist. | +| `cwd` | string | CLI: config file directory
Node.js: `process.cwd()` | Base path that `input` and `output` paths are relative to. | +| `name` | string | `Stylemark` | Display name of the generated styleguide. | -Example `stylemark.config.json`: +Example: -```json +```js { - // [REQUIRED] One or more input path globs. Paths are relative to the config file if present or current working directory otherwise. For globbing patterns, see: https://github.com/sindresorhus/globby/blob/v11.0.0/readme.md#globbing-patterns - "input": ["src/**/*.{jsx,css}", "!*.test.js"], - - // [REQUIRED] Output directory path. Paths is relative to the config file if present or current working directory otherwise. Directories will be automatically created if they don't exist. - "output": "styleguide/", - - // [REQUIRED] Display name of the generated styleguide. - "name": "ACME Styleguide" + input: ["src/**/*.{js,md}", "!*.test.js"], + output: "dist/styleguide", + name: "ACME Styleguide", } ``` -Example `stylemark.config.js`: +### Globbing patterns -```js -module.exports = { - input: ["src/**/*.{jsx,css}", "!*.test.js"], - output: "styleguide/", - title: "ACME Styleguide", -} -``` +- `*` matches any number of characters, but not `/` +- `?` matches a single character, but not `/` +- `**` matches any number of characters, including `/`, as long as it's the only thing in a path part +- `{}` allows for a comma-separated list of "or" expressions +- `!` at the beginning of a pattern will negate the match ## Documenting components diff --git a/bin/cli.js b/bin/cli.js index 130f8a5..7e0e139 100755 --- a/bin/cli.js +++ b/bin/cli.js @@ -26,11 +26,10 @@ const args = require("yargs") const configPath = path.resolve(args.config) const config = require(configPath) - const cwd = path.dirname(configPath) const input = getMatchingFiles(config.input, cwd) const output = path.isAbsolute(config.output) ? config.output : path.resolve(cwd, config.output) -const name = config.name +const name = config.name || "Stylemark" const debounce = config.debounce || 500 const generate = _.debounce(() => stylemark({ name, input, output }, debounce)) diff --git a/docs/examples/stylemark.config.json b/docs/examples/stylemark.config.json new file mode 100644 index 0000000..fc1c5bb --- /dev/null +++ b/docs/examples/stylemark.config.json @@ -0,0 +1,5 @@ +{ + "input": "*.{js,md}", + "output": "../../dist", + "name": "Test Styleguide" +} diff --git a/src/stylemark.js b/src/stylemark.js index 7798790..720c64c 100644 --- a/src/stylemark.js +++ b/src/stylemark.js @@ -9,17 +9,16 @@ const extractCommentBlocks = require("./parse/extractCommentBlocks") const parseComponent = require("./parse/parseComponent") const renderLibrary = require("./render/renderLibrary") -module.exports = config => { - const filepaths = getMatchingFiles(config.input, config.cwd) +module.exports = ({ input, output, name, cwd }) => { + const filepaths = getMatchingFiles(input, cwd) const components = _.flatMap(filepaths, filepath => { const content = fs.readFileSync(filepath, { encoding: "utf8" }) const isMarkdownFile = filepath.endsWith(".md") || filepath.endsWith(".markdown") return isMarkdownFile ? parseComponent(content) : extractCommentBlocks(content).map(parseComponent) }) - const name = config.name const library = new Library({ name, components }) const html = renderLibrary(library) - mkdirp(config.output) - fs.writeFileSync(path.join(config.output, "index.html"), html) + mkdirp(output) + fs.writeFileSync(path.join(output, "index.html"), html) }