Issue with Markdown plugin, since 3.6+
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 15.5k
- Forks
- 1.5k
- Avg merge
- 10d 23h
- Merged PRs (30d)
- 1
Description
Hi, I'm the author of the plugin jsdoc-vuejs and I've just faced a rendering issue with JSDoc 3.6+.
To give you some context, the plugin parse JSDoc to find props/data/methods/... from Vue components, it generates HTML code and inject it into a doclet's description to provide a nice page like this:

But since the last minor realease, it does not fully work anymore. Some code is interpreted as a markdown block and is escaped into <pre><code>...</pre></code> (as you will see below).
Input code
Code from Counter component:
<template>
<div>
{{ counter }}
</div>
</template>
<script>
/**
* @vue-data {Number} [counter=0] Counter value
*/
export default {
name: 'Counter',
data() {
return {
counter: 0,
};
},
mounted() {
this.interval = setInterval(() => this.increment(), 1000);
},
beforeDestroy() {
clearInterval(this.interval);
},
methods: {
/**
* Increment the internal counter.
*/
increment() {
this.counter += 1;
}
}
};
</script>
JSDoc configuration
module.exports = {
plugins: [
'../', // will load jsdoc-vuejs plugin
'plugins/markdown',
],
source: {
include: [
'src/',
'src/better-components',
'src/js',
'README.md',
],
includePattern: '\\.(vue|js)$',
},
opts: {
encoding: 'utf8',
},
};
JSDoc debug output
DEBUG: JSDoc 3.6.0 (Sat, 04 May 2019 22:43:05 GMT)
DEBUG: Environment info: {"env":{"conf":{"plugins":["../","plugins/markdown"],"recurseDepth":10,"source":{"includePattern":"\\.(vue|js)$","excludePattern":"","include":["src/","src/better-components","src/js","README.md"]},"sourceType":"module","tags":{"allowUnknownTags":true,"dictionaries":["jsdoc","closure"]},"templates":{"monospaceLinks":false,"cleverLinks":false},"opts":{"encoding":"utf8"}},"opts":{"_":[],"destination":"docs","configure":".jsdoc.js","debug":true,"encoding":"utf8"}}}
DEBUG: Parsing source files: ["/home/kocal/Dev/jsdoc-vuejs/example/src/Counter.vue","/home/kocal/Dev/jsdoc-vuejs/example/src/better-components/BetterCounter.vue","/home/kocal/Dev/jsdoc-vuejs/example/src/js/CounterJS.js","/home/kocal/Dev/jsdoc-vuejs/example/src/js/NotVueComponent.js","/home/kocal/Dev/jsdoc-vuejs/example/src/js/NotVueComponent2.js"]
Parsing /home/kocal/Dev/jsdoc-vuejs/example/src/Counter.vue ...
Parsing /home/kocal/Dev/jsdoc-vuejs/example/src/better-components/BetterCounter.vue ...
Parsing /home/kocal/Dev/jsdoc-vuejs/example/src/js/CounterJS.js ...
Parsing /home/kocal/Dev/jsdoc-vuejs/example/src/js/NotVueComponent.js ...
Parsing /home/kocal/Dev/jsdoc-vuejs/example/src/js/NotVueComponent2.js ...
DEBUG: Finished parsing source files.
DEBUG: Adding inherited symbols, mixins, and interface implementations...
DEBUG: Adding borrowed doclets...
DEBUG: Post-processing complete.
Generating output files...
Finished running in 0.31 seconds.
Done in 0.42s.
Expected behavior
rendered:

source code:

Note how is rendered the <tr> in <tbody>. It looks like a valid markdown block code and so it's parsed and rendered like a block of code (see below).
Current behavior
rendered:

source code:

A block of code has been parsed and rendered.
Workaround
I've just found a workaround while writing this issue (but I still plan to open it for informational purpose 😄 ). If I remove extra blank lines like this:

then it works for both JSDoc <3.6 and >=3.6.
Your environment
| Software | Version |
|---|---|
| JSDoc | 3.6.0 and more |
| Node.js | 12.7.0 |
| yarn | 1.17.3 |
| Operating system | Debian Stretch |
Thanks :)
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 and reproduce the issue using the supplied Counter.vue example and JSDoc configuration. Compare rendering with JSDoc 3.6.0 and earlier versions, focusing on the extra blank lines that cause the HTML table content to become a code block. Done means the table renders as HTML without removing those blank lines, while the documented workaround remains unnecessary.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100