axe-markdown-loader

allows you to import md files as React components and easy creation of documentation

Stats

stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
41Jun 30, 2018Feb 24, 2018Minified + gzip package size for axe-markdown-loader in KB

Readme

axe-markdown-loader

GitHub license npm version PRs Welcome

Developer-friendly way to automate React component documentation (including automation of props tables & examples).

import SomeMarkdownFile from "./SomeMarkdownFile.md";
<SomeMarkdownFile
    exampleProp="hello"
    anotherProps={() => {
        console.log('world')}
    }
/>

Requirements:

  • Webpack
  • React 16.2.0 or greater

Usage Demo Video

The below demo video will demonstrate how to document any component; in the below example I used ReactTable by react-tools

Screenshot:

Usage Example

Importing Markdown file example:

"App.js" :

import SomeMarkdownFile from "./SomeMarkdownFile.md";

const YourReactComponent = () => (
    <div>
        <SomeMarkdownFile
            propVar={3344}
            propString="Ipsum lorem ;)"
            propFunc={() => {
                console.log('hello')}
            }
        />
    </div>
);

export default YourReactComponent;

Features

  • Import markdown using ES6 import statements.
  • Render React components with JSX fence blocks in your markdown.
    • Optional: show React component's JSX source below render.
  • Edit sources of renders on-the-fly in your browser.
  • Apply CSS to page directly from within your Markdown files using fence blocks.
  • Import other React components, or even any other modules into your markdown files.
  • Display line numbers in source code.

Installation

Step 1: add dependency

npm install axe-markdown-loader --save-dev

or if you use yarn:

yarn add axe-markdown-loader --dev

Step 2: add to webpack config

Add to your webpack module/rules configuration:

{
    test: /\.md/ ,
    loader: ['babel-loader', 'axe-markdown-loader'] ,
    exclude: /node_modules/
}

example webpack.config.js:

module.exports = {
    entry:'./src/entry',
    output: {
        path: path.resolve(__dirname, 'build'),
        filename: '[name].js'
    },
    module: {
        rules: [
            { test: /\.js$/, exclude: /node_modules/, loader: 'babel-loader' },
            { test: /\.md/, exclude: /node_modules/, loader: ['babel-loader', 'axe-markdown-loader'] },
        ]
    }
};

Install styles

@import "~axe-markdown-loader/src/themes/dark.theme";

or use light theme:

@import "~axe-markdown-loader/src/themes/light.theme";

Markdown Guide

Basic Example

# A title

```jsx
<div className="the-best-class-ever">
    Hello
</div>
```                                                       .

Screenshot:

Basic Example

Showing the source code of a React component

Add "show-source" next to fence block language name:

# A title

```jsx show-source
<div>Hello</div>
```                                                       .

Screenshot:

Show Source

Variable Injection

Use #{....} template blocks to inject variables

```jsx show-source

<div>#{ 500 * 500 }</div>

<div className="#{props.someClassName}">hello</div>

#{true ? `<div className="visible">hello #{5 * 5}</div>` : ""}

```                                                       .

Importing modules / other React components

---
imports:
   'reduce': 'reduce-object'
   'TestComponent': './TestComponent'
---

```jsx show-source
<TestComponent
    someProp="lorem ipsum"
/>
```                                                       .

Screenshot:

Importing

Showing only the source without the render:

Add "no-render" next to fence block:

---
imports:
   'reduce': 'reduce-object'
   'TestComponent': './TestComponent'
---

```jsx show-source no-render
<TestComponent
    someProp="lorem ipsum"
/>
```                                                       .

Screenshot:

No Render

Applying CSS to page:

The following will turn the page's background red:

# Paint it red!
```scss show-source
body {
    background: red;
}
```                                                       .

Screenshot:

Paint it Red

Don't apply, just show the source!

Add "no-render" if you don't want to apply your scss styles:

```scss show-source no-render
body {
    background: red;
}
```                                                       .

Screenshot:

Don't Apply CSS

fence blocks inside fence block

When writing markdown examples, use ~~~ to open/close your fence blocks:

# Writing markdown fence blocks

```md show-source
# Title

## The subtitle

~~~css
body {
    background:red;
}
~~~
```                                                       .

Screenshot:

Fence Blocks in Markdown

Hide line numbers

Add "no-line-numbers" if you don't want display the line numbers in the source code:

# A title

```jsx show-source no-line-numbers
<div className="the-best-class-ever">
    Hello
</div>
```                                                       .

Integration with axe-prop-types

Automatically generate PropsTable by using axe-prop-types.

This requires installing axe-prop-types & configuring webpack by following instructions here: axe-prop-types

---                                                       .
imports:
    'ReactLoginPanel': 'react-login-panel'
---                                                       .

## PropTypes
[PROPS_TABLE(ReactLoginPanel)]

Screenshot:

Rendering Component Props Table

License

MIT

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.