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

• markdown-fences
  • Install
  • Usage
    • readContents
    • writeContents
    • injectJsDoc
    • injectFileFencePosts
    • injectToc
  • API
    • readContents
      • Parameters
    • writeContents
      • Parameters
    • injectJsDoc
      • Parameters
      • Examples
    • injectFileFencePosts
      • Parameters
      • Examples
    • injectToc
      • Parameters
      • Examples
    • generateMarkDownFile
      • Parameters
  • Contributing
    • Rules
  • Deployment Steps
  • License

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

• documentation.js - ICS
• markdown-toc - MIT

MIT © psenger