| 1 | # litterate
|
| 2 |
|
| 3 | [](http://npm.im/litterate)
|
| 4 | [](https://packagephobia.now.sh/result?p=litterate)
|
| 5 |
|
| 6 | Litterate is a command line tool to generate beautiful literate programming-style description of your code from comment annotations.
|
| 7 |
|
| 8 | Check out Litterate's own source code, annotated with `litterate`, on [GitHub Pages](https://thesephist.github.io/litterate/).
|
| 9 |
|
| 10 | ## Usage
|
| 11 |
|
| 12 | If you have [`npx`](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b), you can run `litterate` on your project by just running
|
| 13 |
|
| 14 | ```
|
| 15 | npx litterate
|
| 16 | ```
|
| 17 |
|
| 18 | which will run Litterate with the default configuration, found in `./src/defaults.js`.
|
| 19 |
|
| 20 | You can also install `litterate` as a command line tool using `npm install --global litterate`.
|
| 21 |
|
| 22 | You can customize Litterate's output with command line arguments (run `litterate --help` to see options), or with a configuration file, which you can pass to `litterate` with the `--config` command line option.
|
| 23 |
|
| 24 | ## Configuration options
|
| 25 |
|
| 26 | Save your configuration in a file, say `litterate.config.js`, and call Litterate with the config with `litterate --config litterate.config.js`. An example configuration file (the one Litterate uses for itself) is in the repo, at `./litterate.config.js`.
|
| 27 |
|
| 28 | ### `name`
|
| 29 |
|
| 30 | Name of your project, which shows up as the header and title of the generated documentation site.
|
| 31 |
|
| 32 | ### `description`
|
| 33 |
|
| 34 | Description text for your project, shown in the generated site. You can use full Markdown in the description. Litterate uses `marked` to parse Markdown.
|
| 35 |
|
| 36 | ### `files`
|
| 37 |
|
| 38 | An array of file paths to annotate. You can specify file paths as full paths or [glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)). On the main page of the generated site, links to individual files will show up in the order they're listed here.
|
| 39 |
|
| 40 | By default, Litterate annotates all files that match `./src/**/*.js`.
|
| 41 |
|
| 42 | ### `wrap`
|
| 43 |
|
| 44 | If 0, long lines of source code will never be wrapped. If any other number, Litterate will wrap long lines to the given number of characters per line.
|
| 45 |
|
| 46 | ### `baseURL`
|
| 47 |
|
| 48 | By default, the generated website assumes the root URL of the site is '/', but for GitHub Pages and other sites, you may want to set a different base URL for the site. This allows you to set a different site base URL.
|
| 49 |
|
| 50 | ### `verbose`
|
| 51 |
|
| 52 | Verbose output while Litterate runs, useful for debugging.
|
| 53 |
|
| 54 | ### `output`
|
| 55 |
|
| 56 | Specify a different destination directory for the generated docs site. By default, Litterate writes to `./docs/`.
|
| 57 |
|
| 58 | ### `annotationStartMark` and `annotationContinueMark`
|
| 59 |
|
| 60 | By default, Litterate only counts comment blocks that look like this, as annotation blocks.
|
| 61 |
|
| 62 | ```javascript
|
| 63 | //> Start of annotation block
|
| 64 | // continued annotation block
|
| 65 | function add(a, b) {
|
| 66 | // comment that isn't counted
|
| 67 | return a + b;
|
| 68 | }
|
| 69 | ```
|
| 70 |
|
| 71 | This allows you to write `// TODO` comments and other logistical comments without having them be parsed into Litterate annotations. If you'd rather use a different prefix to mark the start and subsequent lines of Litterate anotation blocks, you can override `annotationStartMark` (defaults to `//>`) and `annotationContinueMark` (defaults to `//`).
|
| 72 |
|
| 73 | If you wanted to count all comments, for example, you could override `annotationStartMark` to `//`.
|
| 74 |
|
| 75 | ## Contributing
|
| 76 |
|
| 77 | - `yarn install` to install dependencies (npm should work for these commands too, but the project prefers Yarn and we use a Yarn lockfile.)
|
| 78 |
|
| 79 | - `yarn docs` to run Litterate on itself, with the configuration file in the repo. Note that this generates pages with the `baseURL` set to `/litterate`, for GitHub pages. Run it with `--baseURL /` to use the default root URL.
|