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:
- readContents - an async read file.
- writeContents - an async write file.
- injectJsDoc - builds Markdown JSDocs and injects them into Markdown contents
- injectFileFencePosts - scans ( one pass ) a Markdown file and injects another content into the position
- 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 topath.join
and__dirname
writeContents
Write the given contents ( Markdown as a string ) to the given file.
Parameters
-
file
String The fully qualified output file refer topath.join
and__dirname
-
content
String the content to write to the file. -
options
Object optional options passed tofs#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, defaultfalse
)
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!
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
- we have provided the following:
- Please consider adding an example under examples/ that demonstrates any new functionality
Deployment Steps
- create a pull request from
dev
tomain
- check out
main
npm version patch -m "message here" or minor
npm publish --access public
- Then switch to
dev
branch - And then merge
main
intodev
and pushdev
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