dyn-markdown

Features • Requirements • Usage • Development • About

see table of content

• Features
• Requirements
• Usage
  • Installation
  • Available methods
  • Usage example
• Development
  • Development setup
  • Used technologies
• About
  • Related
  • License
  • Feedback

🎺 Overview

Easily handle dynamic fields in markdown files, such as quantity fields or even tables in nodejs based projects.

In the related section and also in dependents you can see some projects using this package.

🎯 Features

   ✔️ 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.

⚠️ Requirements

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.

💡 Usage

Installation

To install dyn-markdown in your computer, simple run this command:

# install the dyn-markdown npm package
$ npm install dyn-markdown

Available methods

The dyn-markdown 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.

Usage example

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 } from '../src/index';

type RowContent = MarkdownTable['cellContent'][]; // optional, I put here just to teach how to get the type of table rows

const articlesJson = getJson('./examples/articles.json');
const articlesMarkdown = new DynMarkdown('./examples/articles.md');

const articlesTable = new MarkdownTable();

const headerContent: RowContent = [
  { content: 'date', width: 120 },
  { content: 'title', width: 600 },
  { content: 'motivation', width: 300 },
  { content: 'tech', width: 100 }
];

articlesTable.setHeader(headerContent);

articlesJson.forEach((item: any) => {
  const { date, title, motivation, tech } = item;
  const bodyRow: RowContent = [
    { content: date, align: 'center' },
    { content: title, align: 'center' },
    { content: motivation, align: 'left' },
    { content: tech.join(', '), align: 'center' }
  ];
  articlesTable.addBodyRow(bodyRow);
});

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.

🔧 Development

Development setup

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/dyn-markdown

# Go into the repository
$ cd dyn-markdown

# 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

Used technologies

This project uses the following thechnologies:

Scope	Subject	Technologies
Project	Main
Setup	Code linting
	Commit linting
	Other

📚 About

Related

• 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;

License

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.

Feedback

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.

Made with ❤️ by Lucas Vieira

👉 See also all my projects

👉 See also all my articles