Skip to content
This repository has been archived by the owner on May 5, 2024. It is now read-only.

Master #35

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Master #35

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4258896
tidied up and removed console logs
Aug 30, 2016
f8834a9
updated readme to match new regex
Aug 31, 2016
00c15dd
updated readme
Aug 31, 2016
4ceabf0
updated readme
Aug 31, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 13 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
<button class="btn">Click</button>
<a class="btn" href="/some-page">Some Page</a>
```
*/
---*/

.btn {
background-color: black;
Expand Down Expand Up @@ -150,6 +150,13 @@ Default: `'index.html'`

The file to write the style guide to.

#### `markdownFiles`

Type: `String`
Default: `'markdown'`

This is the name of the parent folder that you keep your markdown files in. It is used to try and locate a markdown file if there is no inline markdown and no import is specified in a documentation comment.

## Writing documentation

To add a section of documentation, write a CSS comment that starts with three dashes `---`.
Expand All @@ -159,7 +166,7 @@ To add a section of documentation, write a CSS comment that starts with three da

This is documentation.

*/
---*/
```

```css
Expand All @@ -183,7 +190,7 @@ either a `<button>` or an `<a>` element:
<a class="btn" href="/some-page">Some Page</a>
​```

*/
---*/
```

```html
Expand Down Expand Up @@ -216,7 +223,7 @@ import: buttons.md
---*/
```

The 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.
The contents of a section may be automatically imported as well. For example, had the `import` been omitted, a sibling file of `/markdown/base.buttons.md` or `/markdown/base/buttons.md` would have been used (in that order of preference) if they existed. `/markdown/` being the folder set from `opts.markdownLocation`.

### Details

Expand All @@ -230,7 +237,7 @@ section: Base CSS

Button styles can be applied to **any** element.

*/
---*/
```

```json
Expand Down Expand Up @@ -312,7 +319,7 @@ yakkityyak: Don’t Talk Back

Button styles can be applied to **any** element.

*/
---*/
```

---
Expand Down
53 changes: 22 additions & 31 deletions index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ var isDoc = /\/*-{3}([\s\S]*?)-{3,}/;
var isMeta = /([A-z][\w-]*)[ \t]*:[ \t]*([\w\-\.\/][^\n]*)/g;

module.exports = require('postcss').plugin('mdcss', function (opts) {
// set options object
/* set options object */
opts = Object(opts);

/* set options */
Expand All @@ -17,11 +17,11 @@ module.exports = require('postcss').plugin('mdcss', function (opts) {
opts.assets = (opts.assets || []).map(function (src) {
return path.join(process.cwd(), src);
}); // additional assets path
opts.markdownFiles = opts.markdownFiles || 'markdown'; // location of markdown import files
opts.markdownFiles = opts.markdownFiles || 'markdown'; // markdown import files
if (typeof opts.theme !== 'function') throw Error('The theme failed to load'); // throw if theme is not a function
if (opts.theme.type === 'mdcss-theme') opts.theme = opts.theme(opts); // conditionally set theme as executed theme

// return plugin
/* return plugin */
return function (css, result) {
// set current css directory or current directory
var dir = css.source.input.file ? path.dirname(css.source.input.file) : process.cwd();
Expand All @@ -30,19 +30,17 @@ module.exports = require('postcss').plugin('mdcss', function (opts) {
var list = [];
var hash = {};
var uniq = 0;

// walk comments
/* process documentation comments */
css.walkComments(function (comment) {
// if comment is documentation
// check if comment matches documentation regex, ignore if it doesn't
if (isDoc.test(comment.text)) {
// set documentation object
var doc = {};
var doc = {}; // documentation object

// filter documentation meta
doc.content = comment.text.replace(isDoc, function (isDoc0, metas) {
// push meta to documentation
if (metas) metas.replace(isMeta, function (isMeta0, name, value) {

doc[name] = value.trim();
});

Expand All @@ -52,9 +50,8 @@ module.exports = require('postcss').plugin('mdcss', function (opts) {

// conditionally set the closest documentation name
if (doc.title && !doc.name) { doc.name = doc.title; }
// else if (doc.section && !doc.name) { doc.name = doc.section; }

// conditionally import external content
// if theres no inline/imported markdown specified, look for it...
if (!doc.content) {
// get comment source path
var src = comment.source.input.file;
Expand All @@ -66,47 +63,43 @@ module.exports = require('postcss').plugin('mdcss', function (opts) {
mdbase = doc.import,
mdspec;

// if there's no import specified, look for a md file with the title name inside the section folder
// if there's no import specified, look for a .md file with the title name inside the section folder
if (!mdbase) {
var mdFiles = opts.markdownFiles,
mdSection = doc.section.replace(" ", "-").toLowerCase(),
mdName = doc.title.replace(" ", "-").toLowerCase();
mdName = mdspec = doc.title.replace(" ", "-").toLowerCase();

// look for md file in format of markdown/section/title.md
mdbase = mdFiles + "\/" + mdSection + "\/" + mdName + ".md";
// mdbase = mdspec = path.basename(src, path.extname(src));

// if document has name look for title.name.md file
if (doc.name) {
mdspec += '.' + doc.name;
mdspec = mdFiles + '/' + mdSection + "." + mdName+ ".md";
}

// mdbase += '.md';
// mdspec += '.md';
}

// try to read the closest matching documentation
try {
// if using title.name.md method
if (mdspec) {
doc.content = marked(fs.readFileSync(path.join(localdir, mdspec), 'utf8'));
} else throw new Error();
} catch (error1) {
// then try using markdown/section/title.md
try {
doc.content = marked(fs.readFileSync(path.join(localdir, mdbase), 'utf8'));
} catch (error2) {
doc.content = '';

comment.warn(result, 'Documentation import "' + mdbase + '" could not be read.');
}
}

}
}

doc.content = marked(doc.content, opts.marked);

// set documentation context
doc.context = comment;
doc.content = marked(doc.content, opts.marked); // convert doc object to markdown
doc.context = comment; // set documentation context

// insure documentation has unique name
// console.log(doc.name);
var name = doc.name || 'section' + ++uniq;
var uniqname = name;

Expand All @@ -117,9 +110,7 @@ module.exports = require('postcss').plugin('mdcss', function (opts) {
}
});

// console.log(Object.keys(hash));

// walk hashes
/* walk hashes */
Object.keys(hash).forEach(function (name) {
// set documentation
var doc = hash[name];
Expand Down Expand Up @@ -147,14 +138,13 @@ module.exports = require('postcss').plugin('mdcss', function (opts) {

// make documentation a child of the parent section
parent.children.push(doc);

doc.parent = parent;
}
// otherwise make documentation a child of list
else list.push(doc);
});

// return theme executed with parsed list, destination
/* return theme executed with parsed list and destination */
return opts.theme({
list: list,
opts: opts
Expand All @@ -165,6 +155,7 @@ module.exports = require('postcss').plugin('mdcss', function (opts) {
.then(function () {
return fsp.copy(docs.assets, opts.destination);
})

// then copy the compiled template into the destination
.then(function () {
return fsp.outputFile(path.join(opts.destination, opts.index), docs.template);
Expand All @@ -181,4 +172,4 @@ module.exports = require('postcss').plugin('mdcss', function (opts) {

function titleToName(title) {
return title.replace(/\s+/g, '-').replace(/[^A-z0-9_-]/g, '').toLowerCase();
}
}