axe-markdown-loader

    2.0.5 • Public • Published

    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

    Keywords

    none

    Install

    npm i axe-markdown-loader

    DownloadsWeekly Downloads

    50

    Version

    2.0.5

    License

    MIT

    Unpacked Size

    4.86 MB

    Total Files

    39

    Last publish

    Collaborators

    • sammysaglam