Style Guide api for protocol55.kss and CLI for generating Style Guides from KSS documented CSS. Example Style Guide.
org.clojars.protocol55/styleguide {:mvn/version "0.1.1"}
[org.clojars.protocol55/styleguide "0.1.1"]
[]
[docs]
Returns an ordered sequence of sections of the kss documentation maps of docs
with :reference keys.
[styleguide docs]
Adds the kss documentation maps of docs to styleguide, returning an ordered
sequence of sections.
[styleguide]
[base styleguide]
[base max-depth styleguide]
[base min-depth max-depth styleguide]
Returns an ordered sequence of sections of styleguide constrained by the base,
min-depth and max-depth values.
base - a vector of parts the reference must contain (default [])
max-depth - the maximum depth of the references parts (default Integer/MAX_VALUE)
min-depth - the minimum depth of the references parts (default 0)
[styleguide reference]
Returns the section containing the :reference key reference or nil if not present.
Currently only a couple variations for references are supported. Unless you have a specific reason not to you should always use named references.
Numeric references should be separated by a dot, start at 1 and not have zeros for any of their parts.
Valid numeric references:
- 1
- 1.1
- 200.100.300
Invalid numeric references:
- 0
- 0.1
- 1.0
- 1.0.1
Named references should be separated by a dot and use the following characters:
A-Z a-z _.
Valid named references:
- Components.Buttons
- Components.Buttons.Primary
- Components.Buttons.Button_Sizes.Small
Invalid named references:
- Components.Buttons.Button Sizes.Small
- Components.Buttons.Button-Sizes.Small
Using the weight property in you KSS documentation will re-order that reference within the same depth. You will most likely want to do this for your top-level named references.
- Live reloading of CSS and KSS documentation (via figwheel.main)
- Responsive default theme
- Can generate a static build for hosting
Usage: clj -m protocol55.styleguide.main [options]
Options:
-s, --source DIR Source directory to recursively parse for KSS comments
-m, --mask EXT Extension mask for detecting files containing KSS comments
-r, --root URI / Root uri of the style guide
--css URL URL of a CSS file to include in the style guide
--theme-css URL URL of a CSS file to include to override the default style guide theme
--build-dir DIR Builds an optimized version of the style guide into DIR
--overview FILE File name of the overview's Markdown file
-h, --help
While using the CLI does not require you to write any Clojure code, you will
need to put any files specified with --css or --theme-css within a public
directory on the classpath. This ensures that the server started by
figwheel.main will serve your
files. The most minimal setup would look like the following:
example/
├── resources
│ └── public
│ └── styles.css
└── deps.edn
deps.edn
{:deps {org.clojars.protocol55/styleguide {:mvn/version "0.1.1"}}
:paths ["resources" "target"]}clj -m protocol55.styleguide.main -s resources/ --css styles.css
With styles.css within the public folder in the directory we added to the
classpath via :paths we can now specify it using just the relative path it
will be served from, which in this case is styles.css. If you had put
styles.css inside a nested css directory, such as
resources/public/css/styles.css, you would instead use --css css/styles.css.
Note that you can link to hosted css, such as Google Fonts, by providing the
full url.
We also add target to paths. figwheel.main will generate the javascript used
in the style guide here inside a public folder, so it should also be on the
classpath.