{"id":13646534,"url":"https://github.com/mgalgs/make-readme-markdown","last_synced_at":"2025-03-23T10:43:22.440Z","repository":{"id":50716238,"uuid":"2052108","full_name":"mgalgs/make-readme-markdown","owner":"mgalgs","description":"Convert elisp file header comments to markdown text, suitable for a github README.md file","archived":false,"fork":false,"pushed_at":"2022-10-27T00:16:18.000Z","size":74,"stargazers_count":46,"open_issues_count":5,"forks_count":15,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-15T07:44:23.542Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mgalgs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-07-15T08:29:39.000Z","updated_at":"2025-02-06T13:41:32.000Z","dependencies_parsed_at":"2023-01-20T18:01:55.108Z","dependency_job_id":null,"html_url":"https://github.com/mgalgs/make-readme-markdown","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgalgs%2Fmake-readme-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgalgs%2Fmake-readme-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgalgs%2Fmake-readme-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgalgs%2Fmake-readme-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mgalgs","download_url":"https://codeload.github.com/mgalgs/make-readme-markdown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245090866,"owners_count":20559296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T01:02:58.401Z","updated_at":"2025-03-23T10:43:22.416Z","avatar_url":"https://github.com/mgalgs.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp"],"sub_categories":[],"readme":"\u003ca href=\"https://github.com/mgalgs/make-readme-markdown\"\u003e\u003cimg src=\"https://www.gnu.org/software/emacs/images/emacs.png\" alt=\"Emacs Logo\" width=\"80\" height=\"80\" align=\"right\"\u003e\u003c/a\u003e\n## make-readme-markdown.el\n*Convert emacs lisp documentation to markdown all day every day*\n\n---\n[![License GPLv3](https://img.shields.io/badge/license-GPL_v3-green.svg)](http://www.gnu.org/licenses/gpl-3.0.html)\n\nThis tool will let you easily convert Elisp file comments to markdown text so\nlong as the file comments and documentation follow standard conventions\n(like this file). This is because when you're writing an elisp module, the\nmodule itself should be the canonical source of documentation. But it's not\nvery user-friendly or good marketing for your project to have an empty\nREADME.md that refers people to your source code, and it's even worse if you\nhave to maintain two separate files that say the same thing.\n\n### Features\n\n\n* Smart conversion of standard Elisp comment conventions to equivalent\n  markdown (section headers, lists, image links, etc)\n* Public function documentation from docstrings\n* License badge (auto-detected, see [Badges](#badges))\n* MELPA and MELPA-Stable badges (auto-detected, see [Badges](#badges))\n* Travis badge (auto-detected, see [Badges](#badges))\n* Emacs Icon\n\n### Installation\n\n\nNone\n\n### Usage\n\n\nThe recommended way to use this tool is by putting the following code in\nyour Makefile and running `make README.md` (You don't even have to clone the\nrepository!):\n\n    README.md: make-readme-markdown.el YOUR-MODULE.el\n    \temacs --script $\u003c \u003cYOUR-MODULE.el \u003e$@ 2\u003e/dev/null\n\n    make-readme-markdown.el:\n    \twget -q -O $@ https://raw.github.com/mgalgs/make-readme-markdown/master/make-readme-markdown.el\n\n    .INTERMEDIATE: make-readme-markdown.el\n\nYou can also invoke it directly with `emacs --script`:\n\n    $ emacs --script make-readme-markdown.el \u003celisp-file-to-parse.el 2\u003e/dev/null\n\nAll functions, macros, and customizable variables in your module with\ndocstrings will be documented in the output unless they've been marked\nas private. Convention dictates that private elisp functions have two\nhypens, like `cup--noodle`.\n\n### Badges\n\n\nA license badge is generated if a license can be detected.  Just include\nthe license in your file's comments like normal, taking care to\ncopy/paste the license from its source verbatim.\n\nA MELPA badge is generated if a package is listed on MELPA whose URL\nmatches the URL in your file's pseudo-headers.  Specifically, the URL is\ntaken from that familiar chunk of key-value pairs near the top of your\nfile's pseudo-header comments that usually look something like this:\n\n    ;; Author: Mitchel Humpherys \u003cmitch.special@gmail.com\u003e\n    ;; Keywords: convenience, diff\n    ;; Version: 1.0\n    ;; URL: https://github.com/mgalgs/diffview-mode\n\nIn this case, we would search MELPA for a package whose listed URL\nmatches https://github.com/mgalgs/diffview-mode.  If such a package is\nfound, a MELPA badge is emitted.  The same approach is taken for\nMELPA-Stable.\n\nA Travis badge is generated by querying the Travis API for a project\nwhose `username/repo` key matches the one listed in the URL tag.  So in\nour example above we would query Travis for a project named\n`mgalgs/diffview-mode`.  Currently this only works for projects hosted\non GitHub.\n\n### Syntax\n\n\nAn attempt has been made to support the most common Elisp file comment\nconventions.  Specifically, following patterns at the beginning of a\nline are special:\n\n* `;;; My Header:` ⇒ Creates a header\n* `;; o My list item` ⇒ Creates a list item\n* `;; * My list item` ⇒ Creates a list item\n* `;; - My list item` ⇒ Creates a list item\n\nEverything else is stripped of its leading semicolons and its first\nspace, then is passed directly out.  This means that you can embed\nmarkdown syntax directly in your comments.  For example, you can embed\nblocks of code in your comments by leading the line with 4 spaces (in\naddition to the first space directly following the last semicolon). For\nexample:\n\n    (defun mrm-strip-comments (line)\n      \"Strip elisp comments from line\"\n      (replace-regexp-in-string \"^;+ ?\" \"\" line))\n\nOr you can use the triple-backtic+lang notation, like so:\n\n```elisp\n(defun mrm-strip-comments (line)\n  \"Strip elisp comments from line\"\n  (replace-regexp-in-string \"^;+ ?\" \"\" line))\n```\n\nRemember, if you want to indent code within a list item you need to use\na blank line and 8 spaces. For example:\n\n* I like bananas\n* I like pizza\n\n        (eat (make-pizza \"pepperoni\"))\n\n* I like ice cream with pretty syntax highlighting\n\n```elisp\n(eat (make-ice-cream \"vanilla\"))\n```\n\n* I need to go for a run\n\nWe convert everything between `;;; Commentary:` and `;;; Code` into\nmarkdown. See make-readme-markdown.el for a full example (you might\nalready be looking at it... whoa, this is really getting meta...).\n\nIf there's some more syntax you would like to see supported, submit\nan issue at https://github.com/mgalgs/make-readme-markdown/issues\n\nMany of the functions in this module should probably be \"private\" (named\nwith a double-hypen (\"--\") but are left \"public\" for illustration\npurposes.\n\n\n\n### Function and Macro Documentation\n\n#### `(mrm-strip-comments LINE)`\n\nStrip elisp comments from line\n\n#### `(mrm-strip-file-variables LINE)`\n\nStrip elisp file variables from the first LINE in a file.\nE.g., `-*- lexical-binding: t; -*-'\n\n#### `(mrm-trim-string LINE)`\n\nTrim spaces from beginning and end of string\n\n#### `(mrm-fix-symbol-references LINE)`\n\nFix refs like `this` so they don't turn adjacent text into code.\n\n#### `(mrm-make-section LINE LEVEL)`\n\nMakes a markdown section using the `#` syntax.\n\n#### `(mrm-print-section LINE LEVEL)`\n\nPrints a section made with `mrm-make-section`.\n\n#### `(mrm-slurp)`\n\nRead all text from stdin as list of lines\n\n#### `(mrm-wrap-img-tags LINE)`\n\nWrap image hyperlinks with img tags.\n\n#### `(mrm-print-formatted-line LINE)`\n\nPrints a line formatted as markdown.\n\n#### `(mrm-parse-docs-for-a-thing)`\n\nSearches for the next defun/defmacro/defcustom and prints\nmarkdown documentation.\nReturns a list of the form `(token token-name title-text docstring)`.\nExample return value:\n`(\"defun\" \"document-a-defmacro\" \"(document-a-defmacro CODE)\" \"Takes a defmacro form and...\"`\n\n#### `(mrm-document-a-defcustom CODE)`\n\nTakes a defcustom form and returns documentation for it as a\nstring\n\n#### `(mrm-document-a-defun CODE)`\n\nTakes a defun form and returns documentation for it as a string\n\n#### `(mrm-squeeze-spaces TXT)`\n\nCoalesce whitespace.\n\n#### `(mrm-print-badges LINES)`\n\nPrint badges for license, package repo, etc.\nTries to parse a license from the comments, printing a badge for\nany license found.\n\n#### `(mrm-print-emacs-icon)`\n\nPrint emacs icon to generate a fancy README.md.\n\n-----\n\u003cdiv style=\"padding-top:15px;color: #d0d0d0;\"\u003e\nMarkdown README file generated by\n\u003ca href=\"https://github.com/mgalgs/make-readme-markdown\"\u003emake-readme-markdown.el\u003c/a\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgalgs%2Fmake-readme-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmgalgs%2Fmake-readme-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgalgs%2Fmake-readme-markdown/lists"}