The Markdown Javadoc CLI is fairly simple. The contents of the mdjavadoc --help
command are below.
Usage: mdjavadoc [options]
Options:
-v --version output the version number
-o --output [path] location to output generated files in
-f --file [file] a specific file to parse
-t --template [file] a template to use for generated files
-e --extensions generate files with extensions
--filter [expression] file name filter
--dirfilter [expression] dir name filter
--prefix [url] source code prefix
-b --breadcrumbs [char] generate breadcrumbs
-i --index [name] generate index files with the given name
--index-length [length] number of directories for internal index files to look into
--index-template [file] a template to use for index files
--index-extensions include extensions in index files
-h --help output usage information
More information about this program and how it works can be found in the project README.
Installation
NPM
sudo npm install -g mdjavadoc
From Source
git clone https://github.com/TheAndroidMaster/mdjavadoccd mdjavadoc/clisudo npm install -gsudo npm link
Arguments
--output
By default, mdjavadoc
parses every file (that doesn't start with a .
) in the current directory and outputs the generated markdown in ./docs
. Specifying the --output
argument changes this directory.
--file
Since mdjavadoc
's default behavior is to parse every file in the current directory, the --file
argument has no default behavior. If it is specified, the --output
argument is no longer used as an output directory and can instead be used to specify the file to output markdown into. If --output
is not specified, the output file name defaults to the name of the parsed file + ".md".
--template
This allows you to specify a template file to use for all of the markdown docs generated by the program. Any occurrence of the text {{ content }}
surrounded by whitespace will be replaced with the generated markdown docs.
--extensions
This is used to specify whether extensions should be included in the output file names (the default is no). If this is specified, the markdown file for "ClassName.java" will become "ClassName.java.md" instead of just "ClassName.md".
--filter
This argument can be used to specify a RegEx statement to filter out unwanted files to parse in a directory. This argument defaults to /^(?!\.).*/
, which will exclude any file name which begins with a ".". If you wanted to exclude all files except those which end in .java
, you could set this argument to ".*(\\.java)$"
; likewise for any other file extension.
--dirfilter
--filter
but for directories.
--prefix
This argument is used to specify a prefix to prepend to the source code URLs generated by the program. It defaults to ..
, which you would want if you were placing the docs in a folder with the rest of your source code, but is useless for just about anything else, so you will probably want to change this to your project's complete URL ("https://github.com/user/repository/blob/master").
--breadcrumbs
Specifying this makes mdjavadoc put "breadcrumbs" at the top of generated files to help with navigation. For example, a file "api/index.js" would be given a breadcrumb like this:
[.](../) > [api](.) > **index.js**
You can optionally pass a string to this argument to specify what the divider placed between "crumbs" should be. The default is '>'
.
--index
Specifying this makes mdjavadoc add index files to each directory containing a list of all the files and directories that the directory contains. Optionally, you can pass a string to this argument, which will be used as the name of the index files (they default to "README.md"). These files do overwrite any doc files, however, so you may want to specify --extensions
as well if you happen to have a file named "README.js" or something.
The items displayed in the index files of "internal" directories (any directory except root) are limited to "three folders down" by default, but you can specify --index-length
in addition to this argument to change that.
--index-template
Works literally the exact same way as --template
but for index files.
--index-extensions
Whether to use extensions in the links inside index files.