{"id":13687822,"url":"https://github.com/thesephist/litterate","last_synced_at":"2025-05-12T08:31:30.436Z","repository":{"id":33991646,"uuid":"164930986","full_name":"thesephist/litterate","owner":"thesephist","description":"Generate beautiful literate programming-style description of your code from comment annotations","archived":false,"fork":false,"pushed_at":"2023-09-27T20:38:18.000Z","size":427,"stargazers_count":19,"open_issues_count":6,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-11T20:33:41.391Z","etag":null,"topics":["cli","comments","documentation","literate-programming","nodejs"],"latest_commit_sha":null,"homepage":"https://thesephist.github.io/litterate/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thesephist.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-01-09T20:14:21.000Z","updated_at":"2024-02-28T14:55:14.000Z","dependencies_parsed_at":"2024-01-14T15:23:16.834Z","dependency_job_id":"4f329fdb-3f54-40dd-aa2b-ee6d804a0611","html_url":"https://github.com/thesephist/litterate","commit_stats":{"total_commits":52,"total_committers":2,"mean_commits":26.0,"dds":0.1923076923076923,"last_synced_commit":"2fbdabf526bbf9e28ad38da64812bb56521c892b"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesephist%2Flitterate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesephist%2Flitterate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesephist%2Flitterate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesephist%2Flitterate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thesephist","download_url":"https://codeload.github.com/thesephist/litterate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225130753,"owners_count":17425506,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","comments","documentation","literate-programming","nodejs"],"created_at":"2024-08-02T15:01:01.218Z","updated_at":"2024-11-18T04:46:53.219Z","avatar_url":"https://github.com/thesephist.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","documentation"],"sub_categories":[],"readme":"# litterate\n\n[![npm litterate](https://img.shields.io/npm/v/litterate.svg)](http://npm.im/litterate)\n[![install size](https://packagephobia.now.sh/badge?p=litterate)](https://packagephobia.now.sh/result?p=litterate)\n\nLitterate is a command line tool to generate beautiful literate programming-style description of your code from comment annotations.\n\nCheck out Litterate's own source code, annotated with `litterate`, on [GitHub Pages](https://thesephist.github.io/litterate/).\n\n## Usage\n\nIf you have [`npx`](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b), you can run `litterate` on your project by just running\n\n```\nnpx litterate\n```\n\nwhich will run Litterate with the default configuration, found in `./src/defaults.js`.\n\nYou can also install `litterate` as a command line tool using `npm install --global litterate`.\n\nBy default, Litterate will count comment blocks starting with `//\u003e` on a newline as annotation blocks (see files under `./src/` for examples). This means Litterate works by default for C-style comment languages (JavaScript, Java, C[++], Rust's normal comments). Litterate can be configured to work with pretty much any language that has beginning-of-line comment delimiters, like `#` in Python or `;` in a variety of other languages.\n\nYou 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.\n\n### Usage with npm scripts\n\nGenerally, you'll want to have a configuration you use for your project, and a simple way to run Litterate. For this, one option is to have an npm script that runs Litterate with a configuration file in your project. For example, we may have an npm script:\n\n```js\n    ...\n    \"scripts\": {\n        \"docs\": \"litterate --config litterate.config.js\",\n    },\n    ...\n```\n\nWith this script, running `npm run docs` or  `yarn docs` will run Litterate from your NPM dependencies, with the config file you specified. If you use Litterate this way, there's no need to install Litterate globally; just make sure Litterate is installed for your project as a dependency or devDependency.\n\n## Configuration options\n\nSave 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`.\n\n### `name`\n\nName of your project, which shows up as the header and title of the generated documentation site.\n\n### `description`\n\nDescription text for your project, shown in the generated site. You can use full Markdown in the description. Litterate uses `marked` to parse Markdown.\n\n### `files`\n\nAn 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.\n\nBy default, Litterate annotates all files that match `./src/**/*.js`.\n\n### `wrap`\n\nIf 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.\n\n### `baseURL`\n\nBy 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.\n\n### `verbose`\n\nVerbose output while Litterate runs, useful for debugging.\n\n### `output`\n\nSpecify a different destination directory for the generated docs site. By default, Litterate writes to `./docs/`.\n\n### `annotationStartMark` and `annotationContinueMark`\n\nBy default, Litterate only counts comment blocks that look like this, as annotation blocks.\n\n```javascript\n//\u003e Start of annotation block\n//  continued annotation block\nfunction add(a, b) {\n    // comment that isn't counted\n    return a + b;\n}\n```\n\nThis 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 `//\u003e`) and `annotationContinueMark` (defaults to `//`).\n\nIf you wanted to count all comments, for example, you could override `annotationStartMark` to `//`.\n\n## Contributing\n\n- `yarn install` to install dependencies (npm should work for these commands too, but the project prefers Yarn and we use a Yarn lockfile.)\n\n- `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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthesephist%2Flitterate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthesephist%2Flitterate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthesephist%2Flitterate/lists"}