Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/peopledoc/styledown
Markdown-based styleguide generator
https://github.com/peopledoc/styledown
approved-public css generator ghec-mig-migrated maintainable markdown styleguide
Last synced: 17 days ago
JSON representation
Markdown-based styleguide generator
- Host: GitHub
- URL: https://github.com/peopledoc/styledown
- Owner: peopledoc
- License: mit
- Created: 2020-01-29T15:51:28.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-09-29T22:29:36.000Z (over 1 year ago)
- Last Synced: 2024-04-16T06:52:52.316Z (9 months ago)
- Topics: approved-public, css, generator, ghec-mig-migrated, maintainable, markdown, styleguide
- Language: JavaScript
- Homepage:
- Size: 2.15 MB
- Stars: 0
- Watchers: 30
- Forks: 1
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: History.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Styledown
Write maintainable CSS styleguides efficiently using a Markdown.
ℹ️ This package is forked from [Styledown](https://github.com/styledown/styledown).
## Installation
Add the github registry in your `.npmrc` for @peopledoc scoped package:
```
# Points to Github NPM registry
@peopledoc:registry=https://npm.pkg.github.com
````
Then you can install it:
``` bash
npm install -g @peopledoc/styledown
styledown --help
```
## How it works
Styledown is made to work in most web development setups. It doesn't favor any framework or language or any preprocessor.
* [Document][doc] your CSS files with inline comments, or as a separate `.md` file.
* Create a file with styleguide [configuration][conf].
* Invoke `styledown *.css > styleguide.html`.
* Enjoy your styleguide! Read more about the [format][fmt].
[doc]: docs/Documenting.md
[conf]: docs/Configuration.md
[fmt]: docs/Format.md
## Quickstart guide
Here's a generic guide on getting started with Styledown on any project. We're
gonna assume that you're using Sass and that your project bundles all CSS files
into one file.
Let's assume that your files are in `css/`, and that your final styleguide will
be in `public/styleguide.html`.
```text
Example setup
.----------------------. .---------------------.
| css/ | | |
| config.md | | public/ |
| button.scss | ==> | styleguide.html |
| forms.scss | | |
| whatever.scss | | |
'----------------------' '---------------------'
```
### Step 1: Document
Document your project's stylesheets with inline comments, or as separate `.md`
files.
```css
/**
* Component name:
* `.your-component-here` - documentation on what your
* component is goes here. Markdown is encouraged.
*
* @example
* div.your-component-here
* h3 Sample code
* p goes here
*/
.your-component-here {
display: block;
/*...*/
}
```
Read more: **[Documenting ▸](docs/Documenting.md)**
### Step 2: Configure
Make a file, let's call it `config.md`. (`styledown --conf > config.md`) This
lets you define what will be in the output head/body.
```markdown
# Styleguide options
### Head
link(rel="stylesheet" href="/assets/application.css")
/* styledown css */
/* styledown js */
### Body
h1 My Awesome Styleguides
div#styleguides(sg-content)
```
The first one (`application.css`) should point to your project's concatenated
stylesheets. The second and third one (`styledown.css` and `styledown.js`)
point to the default Styledown CSS/JS files.
Read more: **[Configuration ▸](docs/Configuration.md)**
### Step 3: Build
Invoke `styledown` to generate an HTML file. (Make sure that the extras.css is
passed on the end, since anything after the "Styleguide options" heading is ignored.)
```bash
styledown css/*.css css/config.md > public/styleguides.html
```
### Enjoy!
Now open `public/styleguides.html` in your browser.
## Usage
Styledown generates `.html` styleguides. It can take CSS files or Markdown
files, or a combination of the two.
__Inline CSS mode:__ Parses comments from CSS files. This is what happens when
you pass .css, .sass, .scss, .less and .styl files.
```bash
styledown *.css > styleguide.html
```
__Markdown mode:__ Takes Markdown files.
```bash
styledown *.md > styleguide.html
```
## Markup format
Read more: **[Markup format ▸](docs/Format.md)**
## Contributors
