Nanotech Parading Mars

    @psenger/markdown-fences

    1.0.1 • Public • Published

    markdown-fences

    Markdown-fences provides a set of utilities that create assist in workflow related to building Markdown files, injecting content, table of contents, javascript documentation with metadata tags.

    Features include:

    1. readContents - an async read file.
    2. writeContents - an async write file.
    3. injectJsDoc - builds Markdown JSDocs and injects them into Markdown contents
    4. injectFileFencePosts - scans ( one pass ) a Markdown file and injects another content into the position
    5. injectToc - Scans a markdown and injects a Table of contents.

    Table of contents

    Installation Instructions

    npm install @psenger/markdown-fences --save

    or

    yarn add @psenger/markdown-fences

    Usage

    markdown-fences is a set of utility functions designed to augment Markdown creation. It is made up of the following functions.

    readContents

    const path = require('path');
    const readme = path.join( __dirname, '.README.md' );
    try {
      const readMeContent = await readContents(readMe);
    } catch (e) {
      console.error(e);
    }

    writeContents

    const path = require('path');
    const readme = path.join( __dirname, 'README.md' );
    try {
      const str = `# hello
     welcome to my file
     `;
      await writeContents( readme, str)
    } catch (e) {
      console.error(e);
    }

    injectJsDoc

    Assuming you have these tags in your markdown file called .README.md it will replace it with JavaScript Doc. In this example, the javascript is located in __dirname, src, index.js

    <!--START_SECTION:jsdoc-->
    <!--END_SECTION:jsdoc-->
    
    const path = require('path');
    const readme = path.join( __dirname, '.README.md' );
    try {
      const readMeContent = await readContents(readMe);
      let results =  await injectJsDoc(readMe, [ join(__dirname,'src','index.js') ])
      console.log( results );
    } catch (e) {
      console.error(e);
    }

    injectFileFencePosts

    Reads a Markdown file, finds file injection locations, and injects each file in-line. In this example, it is assumed there is a file called sample.md in the __dirname directory, and will inject the contents in place.

    <!--START_SECTION:file:sample.md-->
    <!--END_SECTION:file:sample.md-->
    
    const path = require('path');
    const readme = path.join( __dirname, '.README.md' );
    try {
      const readMeContent = await readContents(readMe);
      const results = await injectFileFencePosts(readMe, path.join(__dirname), {log:true})
      console.log( results );
    } catch (e) {
      console.error(e);
    }

    injectToc

    Will read the Heading tags EG # Start, ## Level 2-A, and ## Level 2-B and then replace the tags <!--START_SECTION:toc--><!--END_SECTION:toc--> with a Table of contents.

    <!--START_SECTION:toc-->
    <!--END_SECTION:toc-->
    
    const readMe = "# Start\n"
    "<!--START_SECTION:toc-->\n"
    "<!--END_SECTION:toc-->\n"
    "## Level 2-A\n"
    "## Level 2-B \n" ;
    
    let results =  await injectToc(readMe)
    console.log( results );

    API

    readContents

    Read the file contents of a Markdown file into a string

    Parameters

    • file String The fully qualified input file refer to path.join and __dirname

    Returns Promise<string>

    writeContents

    Write the given contents ( Markdown as a string ) to the given file.

    Parameters

    • file String The fully qualified output file refer to path.join and __dirname
    • content String the content to write to the file.
    • options Object optional options passed to fs#writeFile (optional, default {encoding:'utf-8'})

    Returns Promise<void>

    injectJsDoc

    Insert JavaScript Documentation into these fences.

    Parameters

    • markdownContent String The WHOLE read me file, or file that has the TOC Fence in it.
    • indexes Array<String> the fully qualified source files.

    Examples

    File must have these meta Tags to insert the `tutorial.md` file.
      <!--START_SECTION:jsdoc-->
      <!--END_SECTION:jsdoc-->

    Returns Promise<String> The processed content.

    injectFileFencePosts

    Inject a file into the meta tag location.

    Parameters

    • markdownContent String The whole markdown content of a file, that has the TOC Fence in it.

    • baseDir String The base directory for all the fenced files.

    • options Object An option (optional, default {log:false,baseDir:null})

    • options.log Boolean Log flag (optional, default false)

    Examples

    File must have these meta Tags to insert the `tutorial.md` file.
      <!--START_SECTION:tutorial.md-->
      <!--END_SECTION:tutorial.md-->

    Returns Promise<String> The processed content.

    injectToc

    Inject a Table of Contents

    Parameters

    • markdownContent String The whole markdown file, or file that has the TOC Fence in it.

    Examples

    File must have these meta Tags to locate the TOC.
      <!--START_SECTION:toc-->
      <!--END_SECTION:toc-->

    Returns Promise<String> The processed content.

    generateMarkDownFile

    Generate a Markdown File, processing all the fences.

    Parameters

    • markdownFile String The file name of the base file with the fences in it.
    • newMarkdownFile String? The file name of the output file
    • baseDir String The directory path that all inserted files can be found
    • indexes Array<String> The JavaScript files to build the JS Doc from.
    • options Object? Options.

    Returns Promise<void>

    Contributing

    Thanks for contributing! 😁 Here are some rules that will make your change to markdown-fences fruitful.

    Rules

    • Raise a ticket to the feature or bug can be discussed
    • Pull requests are welcome, but must be accompanied by a ticket approved by the repo owner
    • You are expected to add a unit test or two to cover the proposed changes.
    • Please run the tests and make sure tests are all passing before submitting your pull request
    • Do as the Romans do and stick with existing whitespace and formatting conventions (i.e., tabs instead of spaces, etc)
      • we have provided the following: .editorconfig and .eslintrc
      • Don't tamper with or change .editorconfig and .eslintrc
    • Please consider adding an example under examples/ that demonstrates any new functionality

    Deployment Steps

    • create a pull request from dev to main
    • check out main
    • npm version patch -m "message here" or minor
    • npm publish --access public
    • Then switch to dev branch
    • And then merge main into dev and push dev to origin

    License

    MIT License

    Copyright (c) 2021 Philip A Senger

    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    This product uses the following Open Source libraries and is subject to their License

    MIT © psenger

    Install

    npm i @psenger/markdown-fences

    DownloadsWeekly Downloads

    3

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    30.5 kB

    Total Files

    5

    Last publish

    Collaborators

    • psenger