Converting multiple .md files to html
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 15.5k
- Forks
- 1.5k
- Avg merge
- 10d 23h
- Merged PRs (30d)
- 1
Description
I would like to configure JSDoc to output html generated from more than one markdown file in a repo
Input code
Using the markdown plugin, I have configured JSDoc like this:
{
"plugins": ["plugins/markdown"],
"recurseDepth": 10,
"source": {
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_",
"include": [
"./lib/jiff-client.js",
"./lib/client/",
"./lib/jiff-server.js",
"./README.md"
]
},
By default the README.md will be converted into the index.html file for the repo's docs. If I add multiple .md files to the "include" parameter of the config (e.g. adding the CONTRIBUTING.md file so it can appear on the docs website), only one of them is converted (or potentially all of them are but each one overwrites the index.html file).
I would like to be able to include several markdown files and specify their output .html filenames, or have them generated as '*.md > *.html'. As far as I can tell this is not supported by JSDoc at the moment, so I have been regenerating and renaming the index.html file to maintain the output from each markdown file in my repo, which makes the doc-generation process tedious (or the doc build script very complicated).
Is it reasonable to embed the content from all the .md files I'd like to convert in html tags to produce the same type of output I get in the index.html generated from the README? Or is there a way to configure jsdoc to recognize multiple markdown files in a repo?
Thanks!
JSDoc configuration
Here is my full config file:
{
"plugins": ["plugins/markdown"],
"recurseDepth": 10,
"source": {
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_",
"include": [
"./lib/jiff-client.js",
"./lib/client/",
"./lib/jiff-server.js",
"./README.md"
]
},
"sourceType": "module",
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc","closure"]
},
"templates": {
"cleverLinks": false,
"useShortNamesInLinks": true,
"monospaceLinks": false
},
"opts": {
"destination": "./docs/jsdoc/",
"template": "node_modules/docdash"
},
"docdash": {
"collalpse": true,
"search": true,
"menu":{
"Github Repo":{
"href":"https://github.com/multiparty/jiff",
"target":"_blank",
"class":"menu-item",
"id":"github_link"
},
"Tutorial":{
"href":"./intro.html",
"target":"_self",
"class":"menu-item",
"id":"github_link"
},
"Contributing to JIFF":{
"href":"./contributing.html",
"target":"_self",
"class":"menu-item",
"id":"github_link"
}
},
"meta": {
"title": "JIFF Library Documentation"
}
}
}
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the plugins/markdown configuration path and reproduce the supplied config with README.md plus another Markdown file; no source file or test is named in the issue. Done means each included Markdown file can be assigned its own HTML output without overwriting another file, with the generated documentation remaining usable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100