mdol

Simple and easy way to populate Markdowns automatically, like README.md file. Handlebars simpler alternative.

🏗️Project still in very early dev state!

You shouldn't use this right now. I may or not already be using this in some personal projects, but it isn't publicly ready yet. Also, this README is more like a draft right now -- not everything here is already implementeded or even won't ever be.

⤴️ Motivation

• I kept editing by mistake my README.md instead of the README.hbs.
• I wanted some nice warns/reminders on the README.md if that part was code-generated.
• I don't like documentating at all, so I wanted a more plug and play solution, without having to learn too much new stuff about it.
• {{}}, as Handlebars/Mustache uses, is annoying for React project docs.
• Integration with typedoc and typedoc-plugin-markdown.
• Contributors had to deal with the .hbs to change the README. Not newbie friendly at all.
• Inform the contributor where the data is being generated, where it can be changed.
• Inform in the README how to generate the doc.
• Tags for common content, like badges and accessing typedoc content.
• I wanted it to be in my way! 🤠

Philosophy

• Easy for anyone to edit the README. Intuitive and quick to catch up.
• No need to npm i to change the README. The prepare script in .mdol.js must contain npx packages calls or local functions.
• .mdol.js alone should usually be able to contain all the README needs.
• Integration with common tools
• Now focusing in JS/TS env, but it shall also have space for supporting other languages in the future.

Usage

<!--$yourProp-->
<!--/$yourProp-->

Spaces around are allowed: <!--$ yourProp -->

Prop/Segment

Function

• The arguments are parsed as JSON5.
• undefined value is not supported, but null is.
• They may either return a string or an object, so nested access with function returns is supported.

When closing, / before the $!! It's more noticeable that way.

<!--$ @typedoc-md.interface(ShadowI, {table})->>

maybe #? Automatic stringify. Do also allow string version. just {prop} will set it as true.

<!--$badges--> will call badges() with some default argument, like reading .mdol.js badges config. This allows props becoming functions if now it may accept arguments.

<!--$@typedoc-md.interface(ShadowI)-->
<!--/$->

Closes the previous tag.

<!--$yourProp/-->

This will be converted to an open/close tag on compilation.

• In VSCode, if you Ctrl+/ in your .md file, it will comment the current line with <!-- -->. Just add the $ to it!

TODO npx mdol clean - Clear all tags content.

Installation

npm install -D mdol
# or
yarn add -D mdol
# or run directly with npx
npx mdol

Changelog

Name

I somewhat randomly opted for the $ char at the tag, like <!--$yourProp-->. Markdown, md. $, dolar. mdolar? mdol!

Future

• Add guide for people who are contributing to some README.md. Link this guide on the README signs.
• In this guide or near, have the scripts descriptions.
• # tags, for mdol meta/commands usage. Ex:
  • #buildInfo {updatedAt: utcDate, mdolVersion: 'x.x.x', ...}
  • #info, for general comments
  • #for (maybe not needed)
• Maybe, for above, mdol placed tags could have another char, like &.