denoland / denoland/website_feedback

Provide a way to document a directory without a default module

Open
#20 0 comments 1 reaction 0 assignees View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.