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
andtypedoc-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. Theprepare
script in .mdol.js must containnpx
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, butnull
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 &.