denoland / denoland/website_feedback
Provide a way to document a directory without a default module
- Dominant language
- No language data
- Stars
- 8
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
Currently when displaying an index of modules, we extract the module JSDoc tag from the default module in a path and display that as a summary.
If the dir doesn't have a default module, we display nothing, which makes it hard to navigate large collections of modules (like `std`). We need a mechanism/convention to allow this to be documented.
Options I can think of:
- `_mod.md`/`_index.md`/`_doc.md` - contains the markdown to be used to provide a summary.
- Extract the first non-header paragraph of a `README.md` in the dir as a summary.
- `_index.json`/`_mod.json`/`_doc.json` - Contains a [JsDoc](https://doc.deno.land/https://deno.land/x/deno_doc@0.39.0/lib/types.d.ts/~/JsDoc) object which is used to determinate what to display (which could also be rendered as the _readme_ for the path as well, displayed in full markdown like we do when viewing a module).
- Do nothing...
In writing them down, I like the `_doc.json` solution the best, as it would solve a few problems, and we can add the JSON-Schema to the editor extension to help people author the document, though authoring markdown in JSON is yucky. We could of course support more than one, like the `_doc.json` but then try the `README.md` if not present.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.