Skip to content
This repository has been archived by the owner on Nov 3, 2019. It is now read-only.

Commit

Permalink
feat(parser): use a markdown parser
Browse files Browse the repository at this point in the history 
User remark to parse and compile markdown files

close #25
  • Loading branch information
@zkochan
zkochan committed Apr 16, 2016
1 parent 70dd30d commit 675a5c5
Show file tree
Hide file tree
Showing 14 changed files with 181 additions and 166 deletions.
122 changes: 64 additions & 58 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,47 @@
# Contributing

Contents

- [Pull Requests](#pull-requests)
- [Coding Style](#coding)
- [Commit Messages](#commit)


## <a name="pull-requests"></a> Submitting a Pull Request (PR)

Before you submit your Pull Request (PR) consider the following guidelines:

* Search [GitHub](https://github.com/zkochan/mos/pulls) for an open or closed PR
- Search [GitHub](https://github.com/zkochan/mos/pulls) for an open or closed PR
that relates to your submission. You don't want to duplicate effort.
* Make your changes in a new git branch:
- Make your changes in a new git branch:

```shell
git checkout -b my-fix-branch master
```
```shell
git checkout -b my-fix-branch master
```

* Create your patch, following [code style guidelines](#code), and **including appropriate test cases**.
* Run the full test suite and ensure that all tests pass.
* Commit your changes using a descriptive commit message that follows our
- Create your patch, following [code style guidelines](#code), and **including appropriate test cases**.
- Run the full test suite and ensure that all tests pass.
- Commit your changes using a descriptive commit message that follows our
[commit message conventions](#commit). Adherence to these conventions
is necessary because release notes are automatically generated from these messages.

```shell
git commit -a
```
```shell
git commit -a
```

Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files.

* Push your branch to GitHub:
- Push your branch to GitHub:

```shell
git push origin my-fix-branch
```
```shell
git push origin my-fix-branch
```

* In GitHub, send a pull request to `zkochan:master`.
* If we suggest changes then:
* Make the required updates.
* Re-run the test suites to ensure tests are still passing.
* Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
- In GitHub, send a pull request to `zkochan:master`.
- If we suggest changes then:

- Make the required updates.
- Re-run the test suites to ensure tests are still passing.
- Rebase your branch and force push to your GitHub repository (this will update your Pull Request):

```shell
git rebase master -i
Expand All @@ -47,35 +50,34 @@ Before you submit your Pull Request (PR) consider the following guidelines:

That's it! Thank you for your contribution!


### After your pull request is merged

After your pull request is merged, you can safely delete your branch and pull the changes
from the main (upstream) repository:

* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
- Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:

```shell
git push origin --delete my-fix-branch
```
```shell
git push origin --delete my-fix-branch
```

* Check out the master branch:
- Check out the master branch:

```shell
git checkout master -f
```
```shell
git checkout master -f
```

* Delete the local branch:
- Delete the local branch:

```shell
git branch -D my-fix-branch
```
```shell
git branch -D my-fix-branch
```

* Update your master with the latest upstream version:
- Update your master with the latest upstream version:

```shell
git pull --ff upstream master
```
```shell
git pull --ff upstream master
```

### <a id="coding"></a> Coding Style Guidelines

Expand All @@ -86,7 +88,6 @@ Use the [Standard Style](https://github.com/feross/standard) with two exceptions
1. Use trailing commas. [Why you should enforce Dangling Commas for Multiline Statements](https://medium.com/@nikgraf/why-you-should-enforce-dangling-commas-for-multiline-statements-d034c98e36f8#.z1hs2z49c)
2. Don't use parenthesis in arrow functions when they are not required.


### <a name="commit"></a> Commit Message Guidelines

[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg?style=flat-square)](http://commitizen.github.io/cz-cli/)
Expand All @@ -97,55 +98,60 @@ readable messages** that are easy to follow when looking through the **project h
provides command line based wizard to format commit message easily.

### Commit Message Format

Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
format that includes a **type**, a **scope** and a **subject**:

```
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
```
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The **header** is mandatory and the **scope** of the header is optional.

Any line of the commit message cannot be longer 100 characters! This allows the message to be easier
to read on GitHub as well as in various git tools.

#### Revert
If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit. In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted.

If the commit reverts a previous commit, it should begin with `revert:`, followed by the header of the reverted commit. In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted.

#### Type

Must be one of the following:

* **feat**: A new feature
* **fix**: A bug fix
* **docs**: Documentation only changes
* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
- **feat**: A new feature
- **fix**: A bug fix
- **docs**: Documentation only changes
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
semi-colons, etc)
* **refactor**: A code change that neither fixes a bug nor adds a feature
* **perf**: A code change that improves performance
* **test**: Adding missing tests
* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
- **refactor**: A code change that neither fixes a bug nor adds a feature
- **perf**: A code change that improves performance
- **test**: Adding missing tests
- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
generation

#### Scope

The scope could be anything specifying place of the commit change. For example
`plugin-example`, `render-md`, etc.

#### Subject

The subject contains succinct description of the change:

* use the imperative, present tense: "change" not "changed" nor "changes"
* don't capitalize first letter
* no dot (.) at the end
- use the imperative, present tense: "change" not "changed" nor "changes"
- don't capitalize first letter
- no dot (.) at the end

#### Body

Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes".
The body should include the motivation for the change and contrast this with previous behavior.

#### Footer

The footer should contain any information about **Breaking Changes** and is also the place to
reference GitHub issues that this commit **Closes**.

Expand Down
59 changes: 25 additions & 34 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,21 +12,19 @@
[![Test coverage](https://img.shields.io/coveralls/zkochan/mos.svg?style=flat-square)](https://coveralls.io/r/zkochan/mos?branch=master)
<!--/@-->


## Why mos?

* Markdown files are always up to date
* [Examples are always correct][mos-plugin-example]
* [Shields (a.k.a. badges) are auto-generated][mos-plugin-shields]
* Commonly used README sections are auto-generated using info from `package.json`
* Plugins can be used for tons of additional features

- Markdown files are always up to date
- [Examples are always correct][mos-plugin-example]
- [Shields (a.k.a. badges) are auto-generated][mos-plugin-shields]
- Commonly used README sections are auto-generated using info from `package.json`
- Plugins can be used for tons of additional features

## Preview

The [readme][] you are currently reading uses mos!

``` md
```md
<!--@'# ' + package.name-->
# mos
<!--/@-->
Expand All @@ -42,7 +40,6 @@ The [readme][] you are currently reading uses mos!
<!--/@-->
```


<!--@installation()-->
## Installation

Expand All @@ -53,7 +50,6 @@ npm install mos --save
```
<!--/@-->


## Usage

Mos uses a simple templating syntax to execute JavaScript inside markdown files. The result of the JavaScript execution is then inserted into the markdown file.
Expand All @@ -64,7 +60,7 @@ Lets use mos to write a readme with some dynamic data. Have you ever renamed you

**README.md**

``` md
```md
<!--@'# ' + package.name-->
<!--/@-->
```
Expand All @@ -73,7 +69,7 @@ If you view your readme now, it will be empty. However, you have the code that c

Once you've ran `mos`, the readme will look like this:

``` md
```md
<!--@'# ' + package.name-->
# my-awesome-module
<!--/@-->
Expand All @@ -83,66 +79,59 @@ Now your readme has both the code that generates the content and the content its

![Happy cat](http://i.imgur.com/JG9BXxe.jpg)


## CLI Usage

### `mos`

Regenerate the markdown files if they are out of date.


### `mos test`

Test the markdown files. Fails if can't generate one of the markdown files or one of the markdown files is out of date. It is recommended to add this command to the `scripts.test` property of `package.json`.

![](http://i.imgur.com/t6CLmMS.png?1)


#### Optional TAP output

Mos can generate TAP output via `--tap` option for use with any [TAP reporter](https://github.com/sindresorhus/awesome-tap#reporters).

``` console
```console
mos test --tap | tap-nyan
```

![](http://i.imgur.com/jet4ZAG.png?2)


## Plugins

In the usage example the `package` variable was used to access the package info. The variables available in the markdown scope are *declared by mos plugins*. The `package` variable is create by the [package-json](./plugins/package-json) plugin.
In the usage example the `package` variable was used to access the package info. The variables available in the markdown scope are _declared by mos plugins_. The `package` variable is create by the [package-json](./plugins/package-json) plugin.

There are a few mos plugins that are installed with mos by default:

* [package-json](./plugins/mos-plugin-package-json)
* [shields][mos-plugin-shields]
* [license](./plugins/mos-plugin-license)
* [installation](./plugins/mos-plugin-installation)
* [example][mos-plugin-example]
* [dependencies](./plugins/mos-plugin-dependencies)
* [snippet](./plugins/mos-plugin-snippet)
- [package-json](./plugins/mos-plugin-package-json)
- [shields][mos-plugin-shields]
- [license](./plugins/mos-plugin-license)
- [installation](./plugins/mos-plugin-installation)
- [example][mos-plugin-example]
- [dependencies](./plugins/mos-plugin-dependencies)
- [snippet](./plugins/mos-plugin-snippet)

Do you want to write a new one? Read the [plugins readme](./plugins/README.md).


## Who uses mos?

* [magic-hook](https://github.com/zkochan/magic-hook)

- [magic-hook](https://github.com/zkochan/magic-hook)

<!--@license()-->
## License

[MIT](./LICENSE) © [Zoltan Kochan](http://kochan.io)
<!--/@-->

***
* * *

<!--@dependencies({ shield: 'flat-square' })-->
## Dependencies [![Dependency status](https://img.shields.io/david/zkochan/mos.svg?style=flat-square)](https://david-dm.org/zkochan/mos)

- [@zkochan/async-replace](https://github.com/zkochan/async-replace): Regex replacements using asynchronous callback functions
- [acorn](https://github.com/ternjs/acorn): ECMAScript parser
- [callsites](https://github.com/sindresorhus/callsites): Get callsites from the V8 stack trace API
- [chalk](https://github.com/chalk/chalk): Terminal string styling done right. Much color.
Expand All @@ -151,12 +140,12 @@ Do you want to write a new one? Read the [plugins readme](./plugins/README.md).
- [file-position](https://github.com/hughsk/file-position): Given a row/column number, return the index of that character within the whole string
- [github-url-to-object](https://github.com/zeke/github-url-to-object): Extract user, repo, and other interesting properties from GitHub URLs
- [glob](https://github.com/isaacs/node-glob): a little globber
- [linemap](https://npmjs.org/package/linemap): linemap makes conversions between character offsets and line numbers
- [meow](https://github.com/sindresorhus/meow): CLI app helper
- [normalize-newline](https://github.com/sindresorhus/normalize-newline): Normalize the newline characters in a string to `\n`
- [normalize-path](https://github.com/jonschlinkert/normalize-path): Normalize file path slashes to be unix-like forward slashes. Also condenses repeat slashes to a single slash and removes and trailing slashes.
- [read-pkg-up](https://github.com/sindresorhus/read-pkg-up): Read the closest package.json file
- [relative](https://github.com/jonschlinkert/relative): Get the relative filepath from path A to path B. Calculates from file-to-directory, file-to-file, directory-to-file, and directory-to-directory.
- [remark](https://github.com/wooorm/remark): Markdown processor powered by plugins
- [resolve](https://github.com/substack/node-resolve): resolve like require.resolve() on behalf of files asynchronously and synchronously
- [rollup](https://github.com/rollup/rollup): Next-generation ES6 module bundler
- [rollup-plugin-babel](https://github.com/rollup/rollup-plugin-babel): Seamless integration between Rollup and Babel.
Expand All @@ -166,10 +155,10 @@ Do you want to write a new one? Read the [plugins readme](./plugins/README.md).
- [source-map](https://github.com/mozilla/source-map): Generates and consumes source maps
- [tap-diff](https://github.com/axross/tap-diff): The most human-friendly TAP reporter
- [tape](https://github.com/substack/tape): tap-producing test harness for node and browsers
- [unist-util-visit](https://github.com/wooorm/unist-util-visit): Recursively walk over unist nodes

<!--/@-->


<!--@devDependencies({ shield: 'flat-square' })-->
## Dev Dependencies [![devDependency status](https://img.shields.io/david/dev/zkochan/mos.svg?style=flat-square)](https://david-dm.org/zkochan/mos#info=devDependencies)

Expand All @@ -190,12 +179,14 @@ Do you want to write a new one? Read the [plugins readme](./plugins/README.md).

<!--/@-->

***
* * *

**What does mos mean?**
<br>
It means *Markdown on Steroids*!
It means _Markdown on Steroids_!

[readme]: https://raw.githubusercontent.com/zkochan/mos/master/README.md

[mos-plugin-example]: ./plugins/mos-plugin-example

[mos-plugin-shields]: ./plugins/mos-plugin-shields

0 comments on commit 675a5c5

Please sign in to comment.