{"id":15511559,"url":"https://github.com/csstools/mdcss","last_synced_at":"2025-04-28T17:31:14.420Z","repository":{"id":65449696,"uuid":"45187348","full_name":"csstools/mdcss","owner":"csstools","description":"Easily create and maintain style guides using CSS comments","archived":true,"fork":false,"pushed_at":"2018-04-05T18:22:25.000Z","size":53,"stargazers_count":687,"open_issues_count":11,"forks_count":23,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-24T07:25:40.747Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://jonathantneal.github.io/mdcss-theme-github/demo/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/csstools.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-10-29T14:11:54.000Z","updated_at":"2025-04-15T15:50:26.000Z","dependencies_parsed_at":"2023-01-24T03:15:23.711Z","dependency_job_id":null,"html_url":"https://github.com/csstools/mdcss","commit_stats":null,"previous_names":["jonathantneal/mdcss"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstools%2Fmdcss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstools%2Fmdcss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstools%2Fmdcss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstools%2Fmdcss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/csstools","download_url":"https://codeload.github.com/csstools/mdcss/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251343555,"owners_count":21574387,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-02T09:53:07.027Z","updated_at":"2025-04-28T17:31:14.400Z","avatar_url":"https://github.com/csstools.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003cimg src=\"https://jonathantneal.github.io/mdcss-theme-github/demo/logo.png\" height=\"32\"\u003e\n\n\u003cimg align=\"right\" width=\"96\" height=\"96\" src=\"https://jonathantneal.github.io/mdcss-theme-github/demo/mdcss-logo.png\" title=\"mdcss logo\"\u003e\n\n[![NPM Version][npm-img]][npm] [![Build Status][ci-img]][ci]\n\n[mdcss] lets you easily create and maintain style guides with CSS comments using Markdown.\n\n\t/*---\n\ttitle:   Buttons\n\tsection: Base CSS\n\t---\n\n\tButton styles can be applied to any element. Typically you'll want to use\n\teither a `\u003cbutton\u003e` or an `\u003ca\u003e` element:\n\n\t```example:html\n\t\u003cbutton class=\"btn\"\u003eClick\u003c/button\u003e\n\t\u003ca class=\"btn\" href=\"/some-page\"\u003eSome Page\u003c/a\u003e\n\t```\n\t*/\n\n\t.btn {\n\t\tbackground-color: black;\n\t\tcolor: white;\n\t}\n\n## Usage\n\nAdd [mdcss] to your build tool:\n\n```bash\nnpm install mdcss --save-dev\n```\n\n#### Node\n\n```js\nrequire('mdcss').process(YOUR_CSS, { /* options */ });\n```\n\n#### PostCSS\n\nAdd [PostCSS] to your build tool:\n\n```bash\nnpm install postcss --save-dev\n```\n\nLoad [mdcss] as a PostCSS plugin:\n\n```js\npostcss([\n\trequire('mdcss')({ /* options */ })\n]);\n```\n\n#### Gulp\n\nAdd [Gulp PostCSS] to your build tool:\n\n```bash\nnpm install gulp-postcss --save-dev\n```\n\nEnable [mdcss] within your Gulpfile:\n\n```js\nvar postcss = require('gulp-postcss');\n\ngulp.task('css', function () {\n\treturn gulp.src('./css/src/*.css').pipe(\n\t\tpostcss([\n\t\t\trequire('mdcss')({ /* options */ })\n\t\t])\n\t).pipe(\n\t\tgulp.dest('./css')\n\t);\n});\n```\n\n#### Grunt\n\nAdd [Grunt PostCSS] to your build tool:\n\n```bash\nnpm install grunt-postcss --save-dev\n```\n\nEnable [mdcss] within your Gruntfile:\n\n```js\ngrunt.loadNpmTasks('grunt-postcss');\n\ngrunt.initConfig({\n\tpostcss: {\n\t\toptions: {\n\t\t\tprocessors: [\n\t\t\t\trequire('mdcss')({ /* options */ })\n\t\t\t]\n\t\t},\n\t\tdist: {\n\t\t\tsrc: 'css/*.css'\n\t\t}\n\t}\n});\n```\n\n## Options\n\n#### `theme`\n\nType: `NPM Repository`  \nDefault: `require('mdcss-theme-github')`\n\nThe theme used by [mdcss] to create the style guide.\n\n```js\nrequire('mdcss')({\n\ttheme: require('mdcss-theme-github')\n})\n```\n\nTheme-specific options may also be passed in from the theme module itself, but note that any global options would then be ignored.\n\n```js\nrequire('mdcss')({\n\ttheme: require('mdcss-theme-github')(/* options */)\n})\n```\n\n#### `destination`\n\nType: `String`  \nDefault: `'styleguide'`\n\nThe directory to write the style guide to.\n\n#### `assets`\n\nType: `Array`  \nDefault: `[]`\n\nThe list of files or directories to copy into the style guide directory.\n\n#### `index`\n\nType: `String`  \nDefault: `'index.html'`\n\nThe file to write the style guide to.\n\n## Writing documentation\n\nTo add a section of documentation, write a CSS comment that starts with three dashes `---`.\n\n```css\n/*---\n\nThis is documentation.\n\n*/\n```\n\n```css\n/*\n\nThis is not documentation\n\n*/\n```\n\nThe contents of a section of documentation are parsed by Markdown and turned into HTML.\n\n```css\n/*---\n\nButton styles can be applied to **any** element. Typically you'll want to use\neither a `\u003cbutton\u003e` or an `\u003ca\u003e` element:\n\n​```html\n\u003cbutton class=\"btn\"\u003eClick\u003c/button\u003e\n\u003ca class=\"btn\" href=\"/some-page\"\u003eSome Page\u003c/a\u003e\n​```\n\n*/\n```\n\n```html\n\u003cp\u003eButton styles can be applied to \u003cstrong\u003eany\u003c/strong\u003e element. Typically you\u0026#39;ll want to use\neither a \u003ccode\u003e\u0026lt;button\u0026gt;\u003c/code\u003e or an \u003ccode\u003e\u0026lt;a\u0026gt;\u003c/code\u003e element:\u003c/p\u003e\n\n\u003cpre\u003e\u003ccode class=\"lang-html\"\u003e\u0026lt;button class=\u0026quot;btn\u0026quot;\u0026gt;Click\u0026lt;/button\u0026gt;\n\u0026lt;a class=\u0026quot;btn\u0026quot; href=\u0026quot;/some-page\u0026quot;\u0026gt;Some Page\u0026lt;/a\u0026gt;\n\u003c/code\u003e\u003c/pre\u003e\n```\n\nThe contents of a section may also be imported from another file.\n\n**buttons.md**:\n\n\tButton styles can be applied to **any** element. Typically you'll want to use\n\teither a `\u003cbutton\u003e` or an `\u003ca\u003e` element:\n\n\t```html\n\t\u003cbutton class=\"btn\"\u003eClick\u003c/button\u003e\n\t\u003ca class=\"btn\" href=\"/some-page\"\u003eSome Page\u003c/a\u003e\n\t​```\n\n**base.css**:\n\n```css\n/*---\ntitle:  Buttons\nimport: buttons.md\n---*/\n```\n\nThe contents of a section may be automatically imported as well. For example, had the `import` been omitted, a sibling file of `base.buttons.md` or `base.md` would have been used (in that order of preference) if they existed.\n\n### Details\n\nAdditional heading details are added before a second set of three dashes `---` in a section. These heading details are parsed and added to the [`documentation` object](#documentation-object).\n\n```css\n/*---\ntitle:   Buttons\nsection: Base CSS\n---\n\nButton styles can be applied to **any** element.\n\n*/\n```\n\n```json\n{\n\t\"title\": \"Buttons\",\n\t\"section\": \"Base CSS\",\n\t\"content\": \"\u003cp\u003eButton styles can be applied to \u003cstrong\u003eany\u003c/strong\u003e element.\u003c/p\u003e\"\n}\n```\n\n## Writing themes\n\nCreating themes requires an understanding of [creating and publishing npm packages](https://docs.npmjs.com/misc/developers).\n\nThe easiest way to create a new theme is to visit the [boilerplate theme] project page, fork and clone it, and then run `npm install`.\n\nTo create a theme from scratch; create an `index.js` like this one in a new npm package directory:\n\n```js\nmodule.exports = function (themeopts) {\n\t// initialize the theme\n\t// example usage:\n\t// \n\t// require('mdcss')({\n\t//   theme: require('mdcss-theme-mytheme')({ /* opts */ })\n\t// })\n\n\t// return the theme processor\n\treturn function (docs) {\n\t\t// do things with the documentation object\n\t\t// remember to use __dirname to target this theme directory\n\n\t\t// return a promise\n\t\treturn new Promise(function (resolve, reject) {\n\t\t\t// resolve an object with an assets path and a compiled template\n\t\t\tresolve({\n\t\t\t\tassets:   '', // directory of files to copy\n\t\t\t\ttemplate: '' // contents of style guide to write\n\t\t\t});\n\t\t});\n\t};\n};\n\n// this is so mdcss can check whether the plugin has already been initialized\nmodule.exports.type = 'mdcss-theme';\n```\n\nThe `exports` function is where theme options are initialized.\n\n```js\nrequire('mdcss')({\n\ttheme: require('mdcss-theme-mytheme')({ /* theme options */ });\n});\n```\n\nThe `exports` function returns a theme processor. The theme processor is what receives the ordered list of all the parsed `documentation` objects as well as the [options](#options) originally passed into the [mdcss] plugin.\n\n## Documentation object\n\nEach `documentation` object may contain the following properties:\n\n- **title**:    The title of the current section of documentation.\n- **name**:     A unique, hash-safe name of the current section of documentation.\n- **section**:  The proper title of a parent section.\n- **content**:  The body copy of the current section of documentation.\n- **parent**:   The parent section.\n- **children**: An array of child sections.\n- **context**:  The original [`Comment`](https://github.com/postcss/postcss/blob/master/docs/api.md#comment-node) node used to generate the current section of documentation.\n- **import**:  A path to the file representing the content of the current section of documentation.\n\nIn addition to these properties, a `documentation` object includes any additional [details](#details).\n\n```css\n/*---\ntitle:      Buttons\nsection:    Base CSS\nyakkityyak: Don’t Talk Back\n---\n\nButton styles can be applied to **any** element.\n\n*/\n```\n\n---\n\nHave fun, and thanks for using [mdcss].\n\n[ci]:      https://travis-ci.org/jonathantneal/mdcss\n[ci-img]:  https://img.shields.io/travis/jonathantneal/mdcss.svg\n[npm]:     https://www.npmjs.com/package/mdcss\n[npm-img]: https://img.shields.io/npm/v/mdcss.svg\n\n[boilerplate theme]: https://github.com/jonathantneal/mdcss-theme\n\n[Gulp PostCSS]:  https://github.com/postcss/gulp-postcss\n[Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss\n[PostCSS]:       https://github.com/postcss/postcss\n[mdcss]:         https://github.com/jonathantneal/mdcss\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsstools%2Fmdcss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcsstools%2Fmdcss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsstools%2Fmdcss/lists"}