js-to-markdown v1.0.0

JS-TO-MARKDOWN

A node program to generate markdown automatically from js files. Pull requests are welcome! 😃 🎉

Table of Contents

• Getting Started
• Running from command line
• Configuration File
• Configuration File Options
• TAGS used to document the JS Code
• Examples
  • Using @CBAll tag
  • Using @CBStart, @CBEnd tags and markdown comments
  • Generating markdown with PropTypes table
• Roadmap

Getting Started

First install js-to-markdown globaly:

npm install js-to-storybook --global

Running from command line

After installing js-to-markdown globaly, you can run it directly from the command line with a variety of useful options.

Here's how to js-to-markdown using js-to-markdown.config.js as a configuration file:

js-to-markdown -c js-to-markdown.config.js

Configuration File

Is a JavaScript file

module.exports = {
  input: "../path/to/input/dir",
  output: "../path/to/output/dir",
  subfolders: true,
};

Configuration File Options

TAGS used to document the JS Code

To help in the JS Code documentation it is possible to add some tags as commentary in your code to generate a more complete markdown output.

All tags must be placed at the beginning of the line as a commentary.

⚠️ If there is no tag in the file, the entire code will be treated as a block of code, the same behavior as if using the @CBAll tag.

The possible tags that can be used are:

@ignore

This tag is used to tell the script to not parse any line of the JS file.

It has to be placed as the first line of the code.

@CBAll

The @CBAll (CB = Code Block) tag indicates that all lines of JS file needs to be parsed inside a markdown code block notation.

@CBStart and @CBEnd

The @CBStart and @CBEnd (CB = Code Block) indicates that all lines between the start and the end tag will be parsed inside a markdown code block notation.

Examples

Using @CBAll tag

React Native Js code example:

//@CBAll
import React from "react";
import { View, Icon, Container, Text } from "react-native";

export default class Welcome extends React.Component {
  showApp = (event) => {
    const { showApp } = this.props;
    event.preventDefault();

    if (showApp) {
      showApp();
    }
  };

  render() {
    return (
      <Container>
        <View style={styles.mainContent}>
          <Icon name="welcome" size={60} customColor={Colors.Yellow} />
          <Text h3 style={styles.title}>
            JS-TO-MARKDOWN
          </Text>
        </View>
      </Container>
    );
  }
}

This code generates the Welcome.md file at output directory defined in the configuration file with:

import React from \'react\';
import { View, Icon, Container, Text } from \'react-native\';
export default class Welcome extends React.Component {
  showApp = (event) => {
    const { showApp } = this.props;
    event.preventDefault();
    if (showApp) {
      showApp();
    }
  };
  render() {
    return (
      <Container>
        <View style={styles.mainContent}>
          <Icon name=\'welcome\' size={60} customColor={Colors.Yellow} />
          <Text h3 style={styles.title}>
            JS-TO-MARKDOWN
          </Text>
        </View>
      </Container>
    );
  }
}

Using @CBStart, @CBEnd tags and markdown comments

React Native Js code example:

import React from "react";
import { View, Icon, Container, Text } from "react-native";

//# This is the Welcome file
//Exemple code of how to markdown your JS code
//---
export default class Welcome extends React.Component {
  //## Function to be called when the aplication starts
  //@CBStart
  showApp = (event) => {
    const { showApp } = this.props;
    event.preventDefault();

    if (showApp) {
      showApp();
    }
  };
  //@CBEnd

  //---
  //## Render Method
  render() {
    //@CBStart
    return (
      <Container>
        <View style={styles.mainContent}>
          <Icon name="welcome" size={60} customColor={Colors.Yellow} />
          <Text h3 style={styles.title}>
            JS-TO-MARKDOWN
          </Text>
        </View>
      </Container>
    );
    //@CBEnd
  }
}

This code generates the Welcome.md file at output directory defined in the configuration file with:

This is the Welcome file

Exemple code of how to markdown your JS code

Function to be called when the aplication starts

  showApp = (event) => {
    const { showApp } = this.props;
    event.preventDefault();
    if (showApp) {
      showApp();
    }
  };

Render Method

    return (
      <Container>
        <View style={styles.mainContent}>
          <Icon name=\'welcome\' size={60} customColor={Colors.Yellow} />
          <Text h3 style={styles.title}>
            JS-TO-MARKDOWN
          </Text>
        </View>
      </Container>
    );

Generating markdown with PropTypes table

To enable the parse of PropTypes declarations into a table inside markdown is necessary to mark the propTypesToTable flag inside the configuration file as true

React Native Js code example:

import React from "react";
import PropTypes from "prop-types";
import { View, Icon, Container, Text } from "react-native";

//# This is the Welcome file
//Exemple code of how to markdown your JS code
//---
export default class Welcome extends React.Component {
  //## Function to be called when the aplication starts
  //@CBStart
  showApp = (event) => {
    const { showApp } = this.props;
    event.preventDefault();

    if (showApp) {
      showApp();
    }
  };
  //@CBEnd

  //---
  //## Render Method
  render() {
    //@CBStart
    return (
      <Container>
        <View style={styles.mainContent}>
          <Icon name="welcome" size={60} customColor={Colors.Yellow} />
          <Text h3 style={styles.title}>
            JS-TO-MARKDOWN
          </Text>
        </View>
      </Container>
    );
    //@CBEnd
  }
}

Welcome.defaultProps = {
  showApp: () => {},
  type: "highlight",
  seccondButtonMode: "highlight",
};

Welcome.propTypes = {
  /**
   * Function to be called on app starts
   */
  showApp: PropTypes.func,
  /**
   * This props enable the account to be removed after process
   */
  canRemoveAccount: PropTypes.bool.isRequired,
  /**
   * Indicates how the info will be presented to user
   */
  type: PropTypes.oneOf(["highlight", "opacity", "withoutFeedback"]),
  /**
   * Object with the params to be presented
   */
  params: PropTypes.shape({
    documentType: PropTypes.oneOf(DocumentPreviewScreen.DOCUMENT_TYPES)
      .isRequired,
    buttonMode: PropTypes.oneOf(["highlight", "opacity", "withoutFeedback"])
      .isRequired,
    resource: PropTypes.string.isRequired,
    leftButtonLabel: PropTypes.string,
    leftButtonAction: PropTypes.func,
    internalParams: PropTypes.shape({
      resourceLeftLabel: PropTypes.string.isRequired,
      resourceRightLabel: PropTypes.string,
    }),
    rigthButtonLabel: PropTypes.string,
    rigthButtonAction: PropTypes.func,
  }),
  seccondButtonMode: PropTypes.oneOf([
    "highlight",
    "opacity",
    "withoutFeedback",
  ]),
  documentType: PropTypes.oneOf(DocumentPreviewScreen.DOCUMENT_TYPES),
};

This code generates the Welcome.md file at output directory defined in the configuration file with:

This is the Welcome file

Exemple code of how to markdown your JS code

Function to be called when the aplication starts

  showApp = (event) => {
    const { showApp } = this.props;
    event.preventDefault();
    if (showApp) {
      showApp();
    }
  };

Render Method

    return (
      <Container>
        <View style={styles.mainContent}>
          <Icon name=\'welcome\' size={60} customColor={Colors.Yellow} />
          <Text h3 style={styles.title}>
            JS-TO-MARKDOWN
          </Text>
        </View>
      </Container>
    );

PropTypes

ROADMAP

• Parse JSDocs tags to markdown;
• Accept other JS extensions (.jsx, .ts, .tsx, ...) to locate and parse files;
• Configuration option to choose if the Markdown file will be saved at output directory or where the original file is;