jaywcjlove / markdown-to-html-cli

Command line tool that converts markdown to HTML.

markdown-to-html-cli

Converts markdown text to HTML, Provide command line tools and methods. If you are simply converting a small number of Markdown files (or text) into HTML pages, this is very helpful for you.

Usage

Used in Github Actions.

- run: npm i markdown-to-html-cli -g
- run: markdown-to-html --output coverage/index.html
- run: markdown-to-html --source src/README.md --output coverage/index.html
# or
- name: Converts Markdown to HTML
  uses: jaywcjlove/markdown-to-html-cli@main
  with:
    source: README-zh.md
    output: coverage/action.html
    github-corners: https://github.com/jaywcjlove/markdown-to-html-cli
    favicon: data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>🌐</text></svg>

Using With Command.

{
  "scripts": {
    "start": "markdown-to-html --output coverage/index.html"
  },
  "devDependencies": {
    "markdown-to-html-cli": "latest"
  }
}

Used in Nodejs.

import { create } from 'markdown-to-html-cli';

const html = create({
  markdown: 'Hello World! **Bold**\n# Title',
  document: {
    style: ['body { background: red; }'],
  }
});
// => HTML String

Install

$ npm i markdown-to-html-cli

Github Actions

- name: Converts Markdown to HTML
  uses: jaywcjlove/markdown-to-html-cli@main
  with:
    source: README-zh.md
    output: coverage/action.html
    github-corners: https://github.com/jaywcjlove/markdown-to-html-cli
    favicon: data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>🌐</text></svg>

Input Parameters

• output - Output static pages to the specified directory. (default: index.html)
• source - The path of the target file "README.md". (default: README.md)
• description - Define a description of your web page.
• config - Specify the configuration file. (default: package.json)
• markdown - Markdown string
• favicon - Add a Favicon to your Site.
• github-corners - Add a Github corner to your project page.
• corners - Show corners. (default: true)
• dark-mode - Disable light and dark theme styles button. (default: true)
• markdown-style - Markdown wrapper style.
• markdown-style-theme - Setting markdown-style light/dark theme. (dark | light)
• style - Override default styles. css file path or css string
• title - Define the content of the "<title>" document title!

Output Parameters

• output - Output static pages to the specified directory
• markdown - Markdown string
• html - HTML string

Configure in package.json

The configuration can be specified through --config="config/conf.json", It can be in package.json by default.

{
  "markdown-to-html": {
    "document": {
      "title": "markdown-to-html-cli",
      "description": "Command line tool generates markdown as html.",
      "style": "body { color: red; }",
      "meta": [
        { "description": "Command line tool generates markdown as html." },
        { "keywords": "store,localStorage,lightweight,JavaScript" }
      ]
    },
    "favicon": "data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>🌐</text></svg>",
    "github-corners": "https://github.com/jaywcjlove/markdown-to-html-cli",
    "reurls": {
      "README-zh.md": "index.zh.html",
      "README.md": "index.html"
    }
  }
}

• name -> 'markdown-to-html'.title - Define the content of the <title> document title!
• description -> 'markdown-to-html'.description - Define a description of your web page.
• repository.url -> 'markdown-to-html'.github-corners - Add a Github corner to your project page.
• keywords -> 'markdown-to-html'.document.meta - Define keywords for search engines.

Command Help

Usage: markdown-to-html [options] [--help|h]

Options:

  --author                Define the author of a page.
  --config, -o            Specify the configuration file. Default: "<process.cwd()>/package.json".
  --description           Define a description of your web page.
  --favicon               Add a Favicon to your Site.
  --no-corners            Hide Github corner from your project page.
  --github-corners        Add a Github corner to your project page.
  --github-corners-fork   Github corners style.
  --keywords              Define keywords for search engines.
  --no-dark-mode          Disable light and dark theme styles button.
  --markdown              Markdown string.
  --img-base64            Convert images in HTML to base64.
  --style                 Override default styles. css file path or css string.
  --markdown-style-theme  Setting markdown-style light/dark theme.
  --markdown-style        Markdown wrapper style
  --ignore-file           Ignore markdown files under certain paths. Default: "(node_modules)"
  --output, -o            Output static pages to the specified directory. Default: "index.html"
  --source, -s            The path of the target file "README.md". Default: "README.md"
  --title                 The `<title>` tag is required in HTML documents!
  --version, -v           Show version number
  --help, -h              Displays help information.

Example:

  markdown-to-html     --title="Hello World!"
  markdown-to-html     --config="config/conf.json"
  npx markdown-to-html-cli
  npx markdown-to-html-cli **/*.md --output "dist"
  npx markdown-to-html-cli **/*.md --ignore-file="(test)"
  npx markdown-to-html-cli --markdown="Hello World!"
  npx markdown-to-html-cli --no-dark-mode
  npx markdown-to-html-cli --dark-mode auto
  npx markdown-to-html-cli --dark-mode auto --markdown-style-theme dark
  npx markdown-to-html-cli --no-dark-mode --markdown-style-theme dark
  npx markdown-to-html-cli --markdown-style-theme dark
  npx markdown-to-html-cli --github-corners https://github.com/jaywcjlove/markdown-to-html-cli
  npx markdown-to-html-cli --github-corners https://github.com/jaywcjlove --github-corners-fork
  npx markdown-to-html-cli --output coverage/index.html
  npx markdown-to-html-cli --source README.md
  npx markdown-to-html-cli --source README.md --style=./style.css
  npx markdown-to-html-cli --source README.md --style='body { color: red; }'

Markdown Features

Supports for CSS Style

Use HTML comments <!--rehype:xxx--> to let Markdown support style customization.

## Title
<!--rehype:style=display: flex; height: 230px; align-items: center; justify-content: center; font-size: 38px;-->

Markdown Supports **Style**<!--rehype:style=color: red;-->

Support for GFM footnotes

Here is a simple footnote[^1]. With some additional text after it.

[^1]: My reference.

Task lists

To create a task list, preface list items with a regular space character followed by [ ]. To mark a task as complete, use [x].

- [x] #739
- [ ] https://github.com/octo-org/octo-repo/issues/740
- [ ] Add delight to the experience when all tasks are complete :tada:

If a task list item description begins with a parenthesis, you'll need to escape it with \:

- [ ] \(Optional) Open a followup issue

API

import 'markdown-to-html-cli/github-fork-ribbon.css';
import 'markdown-to-html-cli/github.css';

import { ParsedArgs } from 'minimist';
import { Options } from 'rehype-document';
export interface CreateOptions extends MDToHTMLOptions { }
export declare function create(options?: CreateOptions): string;
export interface RunArgvs extends Omit<ParsedArgs, '_'> {
  version?: string;
  source?: string;
  output?: string;
  /** Add a Github corner to your project page. */
  'github-corners'?: string;
  /** Github corners style. */
  'github-corners-fork'?: boolean;
  /** Disable light and dark theme styles button. */
  'dark-mode'?: boolean;
  /** Setting markdown-style light/dark theme. */
  'markdown-style-theme'?: 'dark' | 'light';
  /** Markdown string. */
  markdown?: string;
  /** Markdown wrapper style */
  'markdown-style'?: string;
  /** The `<title>` tag is required in HTML documents! */
  title?: string;
  /** Specify the configuration file. Default: `<process.cwd()>/package.json` */
  config?: string;
  /** Define a description of your web page */
  description?: string;
  /** Define keywords for search engines */
  keywords?: string;
  /** Add a Favicon to your Site */
  favicon?: string;
  /** Define the author of a page */
  author?: string;
  /** Override default styles */
  style?: string;
}
export interface MDToHTMLOptions extends RunArgvs {
  /** [rehype-document](https://github.com/rehypejs/rehype-document#options) options */
  document?: Options;
  /** Rewrite Element. [rehype-rewrite](https://github.com/jaywcjlove/rehype-rewrite#rewritenode-index-parent-void) */
  rewrite?: RehypeRewriteOptions['rewrite'];
  /** rewrite URLs of href and src attributes. */
  reurls?: Record<string, string>;
}
export declare function run(opts?: Omit<RunArgvs, "_">): any;
export declare const cliHelp: string;
export declare const exampleHelp: string;

Related

• markdown-to-html Converts markdown text to HTML.

Development

$ npm i
$ npm run build
$ npm run watch

Related

• html-to-markdown-cli Converts HTML to markdown.

Contributors

As always, thanks to our amazing contributors!

Made with github-action-contributors.

License

MIT © Kenny Wong

markdown-to-html-cli's Issues

How to set background-image?

A nice tool, Thanks!

My question is, how to set background-image for the whole page, thanks!

JEST test support ES Module

Not yet ready: jest cannot run tests correctly in ESM mode and mocking in our tests will need rework. It's possible to have jest convert everything to CJS, however ESM-only features (e.g. import.meta.url) will then fail instead.

Ref:

• https://jestjs.io/docs/ecmascript-modules
• https://kulshekhar.github.io/ts-jest/docs/guides/esm-support/

Jest ESM support:

• jestjs/jest#9430
• nodejs/node#31032
• kulshekhar/ts-jest#1174
• kulshekhar/ts-jest#1709
• jestjs/jest#12183 (comment)

Code:

• e6f29fb

Issue:

• https://stackoverflow.com/a/50052194/1334703
• https://nodejs.org/api/esm.html#esm_no_require_exports_module_exports_filename_dirname

Content outside markdown-style doesn't adapt to dark/light mode changes

When the system changes from light mode to dark mode, the markdown-style element correctly switches style too.

The body itself though does not. Neither does the dark mode switch, nor the github corner (although the github corner still kinda works in dark mode like this).

I see the dark mode switcher already switches CSS variables on the body and those are used in the markdown-style element, so maybe the dark mode switcher could hook into the system event to trigger the same function there, switching everything between modes, then the markdown-style element doesn't need the hook itself (unless there's other CSS in there I haven't seen, I'm not a web dev😅).

style param in Github Action

It appears that style is available in markdown-to-html but not the Github Action, according to README.md, unless one uses package.json. Can you add style to the Github Action?

Change max-width of central body?

So the central body element <markdown-style class="markdown-style"> has a set max-width of 960px, directly on the element. Any way to change this so I can make my site appear wider on wider screens (like max-width: 80%)? Tried putting ".markdown-style": "max-width: 80%" in the package.json config but that doesn't work (which makes sense as the styles are directly on the element).

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update dependency husky to v9
• chore(deps): update dependency lerna to v8
• chore(deps): update dependency lint-staged to v15
• fix(deps): update dependency rehype-prism-plus to v2
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

github-actions

.github/workflows/ci.yml

• actions/checkout v4
• actions/setup-node v4
• peaceiris/actions-gh-pages v4
• ncipollo/release-action v1

.github/workflows/pr.yml

• actions/checkout v4
• actions/setup-node v4

npm

package.json

• @kkt/ncc ^1.1.1
• ajv ^8.8.0
• husky ^8.0.1
• lerna ^7.3.0
• lint-staged ^14.0.1
• prettier ^3.0.0
• tsbb ^4.2.3
• node >=16.0.0

packages/action/package.json

• @actions/core ~1.10.0
• node >=16

packages/cli/package.json

• @types/fs-extra ^11.0.2
• @types/minimist ^1.2.3
• @uiw/github-corners ^1.5.15
• @wcj/markdown-style ^1.0.25
• @wcj/markdown-to-html ^3.0.1
• fs-extra ^11.1.1
• glob ^10.3.10
• image2uri ^2.1.1
• minimist ^1.2.8
• rehype-autolink-headings ^7.0.0
• rehype-document ^7.0.0
• rehype-format ^5.0.0
• rehype-prism-plus 1.6.3
• rehype-slug ^6.0.0
• rehype-urls ^1.2.0
• remark-gemoji ^8.0.0
• node >=16

---

• Check this box to trigger a request for Renovate to run again on this repository

Adding "title" to Github Action

Hi,

thanks for a great tool, it works like a charm. There's one thing missing, though - would you be open to adding title to action.yml? I'd be glad to contribute.

Hide light/dark word on mobile

On mobile the Dark/Light word of the dark mode toggle goes into the actual content. I think it would work to just hide it and rely on the symbol alone to serve as sufficient hint about what it does:

Running github action results in ENOENT: no such file or directory

When providing

- name: Converts Markdown to HTML
        uses: jaywcjlove/markdown-to-html-cli@main
        with:
          source: CrossOriginStuff/DungeonAuraTools/README.md
          output: CrossOriginStuff/DungeonAuraTools.html

it results in

Run jaywcjlove/markdown-to-html-cli@main
source: /home/runner/work/Jodsderechte.github.io/Jodsderechte.github.io/CrossOriginStuff/DungeonAuraTools/README.md
error:: [Error: ENOENT: no such file or directory, open '/home/runner/work/Jodsderechte.github.io/Jodsderechte.github.io/CrossOriginStuff/DungeonAuraTools/README.md'] {
  errno: -2,
  code: 'ENOENT',
  syscall: 'open',
  path: '/home/runner/work/Jodsderechte.github.io/Jodsderechte.github.io/CrossOriginStuff/DungeonAuraTools/README.md'
}
Error: ENOENT: no such file or directory, open '/home/runner/work/Jodsderechte.github.io/Jodsderechte.github.io/CrossOriginStuff/DungeonAuraTools/README.md'

even when using the "copy path" function of said README. The repository seems to be included twice in the path which is weird and might be the source of the problem. If you need any more help or if i'm just stupid let me know