mdol
TypeScript icon, indicating that this package has built-in type declarations

0.1.0 • Public • Published

mdol

PRs Welcome TypeScript npm npm

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 &.

Readme

Keywords

none

Package Sidebar

Install

npm i mdol

Weekly Downloads

0

Version

0.1.0

License

ISC

Unpacked Size

4.83 kB

Total Files

2

Last publish

Collaborators

  • srbrahma