JSPM

Features • Requirements • Usage • Development • Help • About • Community

🎺 Overview

The main goal of dyn-markdown is to provide a way to quick and easily update markdown fields in nodejs based projects.

🎯 Features

   ✔️ easily add, update or remove markdown fields (numbers, tables, etc);
   ✔️ provides an easy way to get content form json files;
   ✔️ 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;
   ✔️ 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.

If you want to make changes to the source code, it is recommended to also install the following items:

• git: To work with version controlling;
• vscode: Useful for editing the code. You can choose a similar editor as you wish.

💡 Usage

Installation

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

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

After that you will be able to use normally.

Properties and methods

The dyn-markdown comes with the following commands list:

just to mention, the RowContent has the following type:

type RowContent = {
  content: string;
  width?: number;
  align?: 'center' | 'left' | 'right' | 'justify';
};

Simple example

Lets supose we have a markdown file ('./articles.md') with the following content, where we want to update the fields: ARTICLES_NUMBER, TECH_TABLE.

<h3 align="center">
  <!-- <DYNFIELD:ARTICLES_NUMBER> -->
  ALL MY ARTICLES (70)
  <!-- </DYNFIELD:ARTICLES_NUMBER> -->
</h3>

<h3>NODEJS UTILITIES</h3>

<div align="center">
  <!-- <DYNFIELD:NODEJS_UTILITIES> -->
    <table>
      <tr>
        <th align="left" width="120">date</th>
        <th width="600">title</th>
        <th width="300">motivation</th>
        <th width="100">tech</th>
      </tr>
      <tr>
        <td align="center">28-07-2020</td>
        <td align="center">How to set .env variables to Heroku dynamically with a .sh script</td>
        <td align="left">This is very useful when your repository has a lot of changes in .env variables, so you dont need to update them manualy in heroku.</td>
        <td align="center">heroku, bash</td>
      </tr>
    </table>
  <!-- </DYNFIELD:NODEJS_UTILITIES> -->
</div>

we also have the following JSON file (./articles.json):

[
  {
    "date": "28-07-2020",
    "title": "How to set .env variables to Heroku dynamically with a .sh script",
    "motivation": "This is very useful when your repository has a lot of changes in .env variables, so you dont need to update them manualy in heroku.",
    "tech": ["heroku", "bash"]
  },
  {
    "date": "28-07-2020",
    "title": "How to add “Open with Windows Terminal” option to the context menu",
    "motivation": "This is great for open the terminal in the folder you want directly, without having to use commands such as 'cd'.",
    "tech": ["windows", "windows terminal"]
  },
  {
    "date": "27-07-2020",
    "title": "How to add “Open with WSL VS Code” to Windows Context Menu",
    "motivation": "This is great for open the vscode in the folder you want directly, without having to use commands such as 'cd'.",
    "tech": ["windows", "vscode"]
  },
  {
    "date": "27-07-2020",
    "title": "How to add a .bashrc equivalent to the windows cmd terminal",
    "motivation": "This is useful to set your custom commands and functions and load them right away, instead of manually loading them.",
    "tech": ["windows"]
  }
]

so we create a typescript file (update-content.ts) with the following content:

import { DynMarkdown, MarkdownTable, getJson } from 'dyn-markdown';

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

const articlesTable = new MarkdownTable();
articlesTable.setHeader([
  { content: 'date', width: 120 },
  { content: 'title', width: 600 },
  { content: 'motivation', width: 300 },
  { content: 'tech', width: 100 }
]);
articlesJson.forEach((item: any) => {
  const { date, title, motivation, tech } = item;
  const bodyRow: any = [
    { 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());
articlesMarkdown.updateField('ARTICLES_NUMBER', 'ALL MY ARTICLES (70)');
articlesMarkdown.saveFile();

after run the above typescript code, all the content will be replaced. For more information, see the working example at the EXAMPLES folder.

🔧 Development

Development setup

To setup this project in your computer, download it in this link or run the following commands:

# Clone this repository
$ git clone https://github.com/lucasvtiradentes/dyn-markdown

# Go into the repository
$ cd dyn-markdown

After download it, go to the project folder and run these commands:

# Install dependencies
$ npm install

# Run the typescript code in development mode
$ npm run dev

If you want to contribute to the project, 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 compiled code in production mode
$ npm run start

Folders and files structure

The project has the following folder strucure:

|-- .github         # contains CI-CD workflows, github templates, DOCS and images.
|-- .husky          # contains git hooks configurations files.
|-- .vscode         # contains vscode settings for this project.
|-- coverage        # (dev only) test coverage folder
|-- dist            # (dev only) build folder
|-- docs            # documentation folder
|-- examples        # examples folder
|-- node_modules    # (dev only) dependencies folder
|-- scripts         # scripts to help development
|-- src             # application source code
|-- tests           # tests folder

and the filles present in root folder are the following:

# IGNORED FILES
.eslintignore     # eslint ignored items
.gitignore        # git ignored items
.prettierignore   # prettier ignored items
.npmignore        # npm package ignored items

# COMMIT LINTING
.commitlintrc     # commitlint settings
.czrc             # commitizen settings

# SOURCE CODE LINTING
.eslintrc         # eslint settings
.prettierrc       # prettier settings
.editorconfig     # editorconfig settings
.lintstagedrc     # lintstaged settings

# OTHER FILES
.tsconfig.json    # typescript settings
package.json      # project specifications
release.config.js # ci-cd npm package deployment configs
LICENSE           # application license

Used technologies

dyn-markdown uses the following thechnologies:

Scope	Subject	Technologies
Main	Main
Setup	Code linting
	Commit linting
	Other

And also this project used the following packages:

# DEV DEPENDENCIES (skiped @types/*)

- @commitlint/cli           # commitlint cli tool
- commitizen                # commit messages using pre-set of options;
- commitizen-emoji          # preset of options to commitzen using gitmoji;
- commitlint                # commit messages validation
- commitlint-config-gitmoji # preset of settings to commitlint using gitmoji;
- eslint                    # linting source code;
- eslint-config-prettier    # integration between eslint and prettier;
- husky                     # automation of git hooks;
- lint-staged               # lint only changed files, instead of the entire project;
- prettier                  # code formatting;
- ts-node                   # typescript runner;
- typescript                # javascript superset tool;

Code style

There's not a named convention used in this project (like airbnb, for instance), instead we specified he settings we like the most in prettier. You can check these settings in the .prettierrc file.

Commit messages style

This project uses the best of two main conventions to commit messages validation:

• conventional commits: it's powerfull messages structure;
• gitmoji: it's beutiful and visual way to display commits.

So a typically valid commit message has this pattern:

🔧 config: add lint-staged to the project (#2)

Also, in order to have this integration working correctly, I buld a script that we can specify only allowed types and it take care to update both commitizen and commitlint settings.

Tests

Warning ⚠️ This project does not have tests yet, but you in the future we will be adding some.

🙏 Help

FAQ

You can check our most common questions and awnsers in this link.

Docs and support

The first point of call should be our Github discussions. Ask your questions about bugs or specific use cases, and someone I will respond as soon as possible. Or, if you prefer, open an issue on our GitHub repo.

📚 About

Roadmap

In the near future we intend to add these features:

• add tests using jest;
• correct some english mistakes I might have made;

Also, you can check our issues to see other in development features.

Related

The most related links to this project are:

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

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

👪 Community

Contributing

If you are a typescript developer, we would kind and happy accept your help:

• The best way to get started is to select any issue from the good-first-issue label;
• If you would like to contribute, please review our Contributing Guide for all relevant details.

Another ways to positivily impact this project is to:

• ⭐ Star this repository: my goal is to impact the maximum number of developers around the world;
• ✍️ Fix english mistakes I might have made in this project, may it be in the DOCS or even in the code (I'm a portuguese natural speaker);
• ❤️ Say thanks: kind words have a huge impact in anyone's life;
• 💰 Donate: if you want to support my work even more, consider make a small donation. I would be really happy!

Feedback

Any questions or suggestions? You are welcome to discuss it on:

• Github discussions
• Email

Acknowledgements

This project is an idea of @lucasvtiradentes to return some value to the world after years of consuming a lot of useful tools provided by this amazing open source community.