thomas11 / md-readme Goto Github PK

I really like this project, it's a great idea. I ran it on one of my projects and it built an almost identical README.md to the one I was maintaining by hand, which is very nice.

If you can detect when there are formatted blocks (e.g. indented with spaces), and detect that the block contains elisp (perhaps, if there is a leading semicolon), it could add three-backticks "elisp" around them, as can be seen in this diff of my my README.md vs the one md-readme generated:

mrc/live-cricket@ef21138

The sample Makefile shows one way to render a targeted file.

Cask offers a mechanism for running commands defined by emacs packages - commands included in a package's bin/ directory can be run with cask exec <command-name>.

If we put the following in bin/md-readme:

#! /bin/sh

exec "$EMACS" -batch "$@" -l md-readme -f mdr-generate

then any project that lists md-readme as a dev dependency in its Caskfile can render its readme by just running

cask exec md-readme <target-file>

Would you accept a PR to add that command to the package?

I've been happily using md-readme for skewer-reload-stylesheet's readme.

However, I just noticed an impedance mismatch between quoting variable names in comments and Markdown's syntax, which you can see here.

In Markdown, backticks are paired, while in elisp, backticks are paired with single quote, resulting in the wrong highlighting you see in the third paragraph of the above-linked section.

I've come to use backtick-quoted varnames in elisp comments because they get syntax-colored correctly, and you can jump directly to their definition when using elisp-slime-nav-mode.

The original Markdown description and the CommonMark spec say you can escape leading backticks like this: `var-name', and as you can see, it works in GitHub's Markdown parser, yielding ``var-name'`.

So, it looks to me like the thing to do is to search-and-replace ``backtick-quoted-names'with ```backtick-quoted-names' ``` when rendering the document.

Thoughts?

Hey, I just re-discovered this project while working on a small Emacs library.

While writing my elisp documentation, I realized I wanted to call out particular variables and functions as things a user might want to customize.

It seemed like a good place to use the docstrings I've written for those functions and variables, rather than having to maintain a list of interesting vars and functions by hand in the commentary section.

Would you accept a PR to add a mechanism for embedding variable and function names/docstrings in the generated readme?

I was thinking of using comments starting with ;;% to mean 'evaluate this block as elisp and embed the result in the generated doc', but that might be overkill.

Any thoughts?