Skip to content
main
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
doc
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

2md: convert formatted text to markdown

There are lots of packages for turning markdown into html, but this one goes the other way, turning formatted html into markdown.

Say you’re reading an Ars Technica article and want to copy something into some markdown notes. Just select some content in your browser, copy it, then run 2md. The heading, list formatting, bold text, and hyperlinks are all preserved.

You can try it out online at 2md.ca.

A detailed writeup of the internals exists: “Compiling HTML to Markdown with TypeScript: How 2md works

Installation

The easiest way to try out 2md from the command line is with npx, a tool to automatically download, cache, and run programs; it’s been included with Node.js since 2017:

npx 2md [--no-quote] [FILE]

You can also install to install the 2md command with yarn:

yarn [global] add 2md

Usage

Run

npx 2md [--no-quote] [FILE]

to get markdown.

By default, 2md reads from the clipboard, using osascript, xclip, or powershell. Otherwise, pass it the name of html file as a command-line argument.

For easy inserting of stuff into other documents, --quote is on by default and wraps the markdown in a blockquote:

> # Foo
>
> bar ...

API

Only a single function is exposed: toMd.

const { toMd } = require('2md');

console.log(toMd('foo <b>bar</b>'));

prints

foo **bar**

Only exported files with public in the path are supported. Everything else is subject to change without notice. But if there’s some interesting code here you’d like to reuse, let me know and I can look into publishing it as a separate package.

Contributing

Contributions are welcome! There are fairly comprehensive end-to-end and round-trip tests, and TypeScript’s type-checking makes refactoring safer, so don’t be afraid to move code around.

License

All the original code here is licensed under the Apache License, version 2.0, included in LICENSE.code; except for the contents of the “how it works” article how-it-works/post.mdx, which is not redistributable.

Releasing

The current release process, to be automated later, is:

  1. Remove the -pre tag from the version field in core/package.json version, and from the 2md dependency in website/package.json

  2. Update CHANGELOG.md

  3. Commit to git, and git tag vA.B.C

  4. git push --tags $REMOTE main

    Optional: figure out automation to put CHANGELOG.md excerpt into auto-created GitHub releases.

  5. In the core directory, yarn run package and inspect tarball

  6. npm publish 2md-vA.B.C.tgz

    If publishing a pre-release, add npm publish --tag next to set the correct npm tag.

  7. Bump version and add -pre version suffix in core/package.json; update the 2md dependency version in website/package.json as well

    Otherwise yarn won’t use the local version.

    The yarn workspaces documentation says,

    if workspace-b depends on a different version than the one referenced in workspace-a’s package.json, the dependency will be installed from npm rather than linked from your local filesystem. This is because some packages actually need to use the previous versions in order to build the new ones (Babel is one of them).
You can’t perform that action at this time.