How to install a man page into a node.js app

Readme.md

How to install a man page into a node.js app

Installing a man page is not easy as there are little infos out there about it.

After a lot of trial and error, google searches and alpha publishing my app I finally have a collection of things I need to do to get it working:

1. Create a roff file
   • You can use https://github.com/kapouer/marked-man to convert mardown to roff
   • Make sure you have a headline and several sub headlines like so:

   CUTTLEBELLE
   ===========
   
   > Cuttlebelle - The react static site generator that separates editing and code concerns
   
   
   ## SYNOPSIS
   
   `cuttlebelle  [init]  [-i]  [docs]  [-d]  [watch]  [-w]  [--no-generate]  [-n]  [--silent]  [-s]  [--version]  [-V]  [--verbose]  [-v]`
   
   
   ## DESCRIPTION
   
   Cuttlebelle is a react static site generator that separates editing and code concerns.
   
   
   ## EXAMPLES
   etc

   For a full example look at https://raw.githubusercontent.com/cuttlebelle/cuttlebelle/master/man/man.md
   • Name the file the same as your bin command. So if your bin command is cuttlebelle the name of the file should be cuttlebelle.1
   • A handy npm script would be:

      "scripts": {
      	"prepublish": "npm run man",
      	"man": "cd man && marked-man --version 'v1.0.0' --manual 'Cuttlebelle Help' --section 1 man.md > cuttlebelle.1"
      }

2. Test your roff file locally
   • cd into your man folder and run man ./cuttlebelle.1 to see what it looks like
   • Tweak until pretty :)
3. Add your roff file to your package.json
   • Derived from others you need to add below to your package.json:

      "directories": {
      	"man": "man"
      },
     

     (We assume here you placed your roff file into the ./man folder.)
   • Do not add the man array or anything else man related
4. Test your man page locally
   • After you saved all files above rerun npm link. This will and should make the man page available to you locally before publishing.
   • If it does not work recheck everything above
5. Publish
   • Perhaps publish via an alpha tag first to make sure. Do via changing your current version to x.x.x-alpha.1 and run npm publish --tag alpha. Plublishing an alpha version and tagging it will prevent anyone from getting this version unless they secify that tag
   • Now install your app globally by specifying the version or tag: npm i -g yourapp@alpha
   • Try man yourapp
   • If successful change your version to x.x.x and run npm publish
   • 🔥 done!

manpage.gif

Right now there is a bug where npm does not support 'directories.man' AND does not support setting the man page as a string.

You must provide an array:

"man": ["man/example.1"]

instead of

"directories": ...