Features β’ Requirements β’ Usage β’ Development β’ About
see table of content
Easily handle dynamic fields in markdown files, such as quantity fields or even tables in nodejs based projects.
Β Β Β βοΈ easily add, update or remove markdown fields (numbers, tables, etc);
Β Β Β βοΈ powerful and simple way to deal with tables;
Β Β Β βοΈ allow you to see the current content before you update the file;
Β Β Β βοΈ allow you to see which dynamic fields were found;
Β Β Β βοΈ provides an easy way to get content form json files;
Β Β Β βοΈ works in typescript, javascript commonjs and javascript modules.
In order to use this project in your computer, you need to have the following items:
- npm: To install the package. Npm is installed alongside nodejs;
- nodejs: To actually run the package.
To install markdown-helper
in your computer, simple run this command:
# install the markdown-helper npm package
$ npm install markdown-helper
The markdown-helper
comes with the following commands list:
Exported | Command | Description |
---|---|---|
DynMarkdown | .markdownContent |
Access the current markdown file content. |
.fields |
Shows the dynamic fields found on the specified file. | |
.updateField(field, newContent) |
updates the field with the newContent provided. | |
.deleteField(field) |
delete an existing field in the markdown content. | |
.addSection(content, position, searchedLine?) |
add a content to a specific position in the markdown. | |
.saveFile({path?, overwrite?}) |
update the markdown file. you can either save into the same read file or in another one. | |
.listHeadingsItemsByStartPattern(startLinePattern) |
get the headings items by line start pattern. | |
MarkdownTable | .addBodyRow(RowContent[]) |
add a row to the table body. |
.getTable(columnToJoin[]?) |
get the table final content. if specified it also merge rows with the same value. | |
getJson | N/A | get the json content of a file. |
In the examples folder there is a intermediary example that uses most of the package features.
In short words, we have a articles.json and we want to update two dynamic fields in a readme file called articles.md:
- quantity of articles
- table with article informations, such as title and author;
In the articles.md we have to specify every dynamic field with a special html-like syntax, as it is shown below:
<h3 align="center">
<!-- <DYNFIELD:ARTICLES_NUMBER> -->
ALL MY ARTICLES (4)
<!-- </DYNFIELD:ARTICLES_NUMBER> -->
</h3>
To update all the desired fields, we create a typescript file with the following content:
import { DynMarkdown, MarkdownTable, getJson, TRowContent } from '../../src/index';
type TArticleItem = {
date: string;
title: string;
motivation: string;
tech: string[];
};
type TArticleFields = 'LAST_UPDATE_BY' | 'NODEJS_UTILITIES' | 'ARTICLES_NUMBER';
const articlesJson: TArticleItem[] = getJson('./examples/articles/articles.json');
const articlesMarkdown = new DynMarkdown<TArticleFields>('./examples/articles/articles.md');
const headerContent = [
{ content: 'date', width: 120 },
{ content: 'title', width: 600 },
{ content: 'motivation', width: 300 },
{ content: 'tech', width: 100 }
] as const satisfies TRowContent;
const articlesTable = new MarkdownTable(headerContent);
articlesJson.forEach((article) => {
const { date, title, motivation, tech } = article;
const bodyRow: TRowContent = [
{ content: date, align: 'center' },
{ content: title, align: 'center' },
{ content: motivation, align: 'left' },
{ content: tech.join(', '), align: 'center' }
];
articlesTable.addBodyRow(bodyRow);
});
articlesMarkdown.updateField('LAST_UPDATE_BY', 'javascript ts');
articlesMarkdown.updateField('NODEJS_UTILITIES', articlesTable.getTable(['date']));
// articlesMarkdown.updateField('ARTICLES_NUMBER', `ALL MY ARTICLES (${articlesJson.length})`);
// articlesMarkdown.saveFile();
After run the above typescript code, all the content will be replaced.
If you want to contribute to the project it is recommended to also install the following tools:
- git: To work with version controlling;
- vscode: Useful for editing the code. You can choose a similar editor as you wish.
To setup this project in your computer run the following commands:
# Clone this repository
$ git clone https://github.com/lucasvtiradentes/markdown-helper
# Go into the repository
$ cd markdown-helper
# Install dependencies
$ npm install
# Run the typescript code in development mode
$ npm run dev
After you make the necessary changes, run these commands to check if everything is working fine:
# Compiles the typescript code into javascript
$ npm run build
# Run the available unit tests
$ npm run test
# Run the compiled code in production mode
$ npm run start
This project uses the following thechnologies:
- js-boilerplates: boilerplates repository that uses this package to update boilerplate lists;
- my-tutorials: my github tutorials repository that uses this package to update articles, projects and other stuff;
This project is distributed under the terms of the MIT License Version 2.0. A complete version of the license is available in the LICENSE file in this repository. Any contribution made to this project will be licensed under the MIT License Version 2.0.
If you have any questions or suggestions you are welcome to discuss it on github issues or, if you prefer, you can reach me in my social media provided bellow.