Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow users to customize the Markdown highlighter code #1412

Closed
hegemonic opened this issue Jul 22, 2017 · 1 comment
Closed

Allow users to customize the Markdown highlighter code #1412

hegemonic opened this issue Jul 22, 2017 · 1 comment
Labels
Milestone

Comments

@hegemonic
Copy link
Contributor

hegemonic commented Jul 22, 2017

For code snippets, jsdoc/util/markdown applies a specific set of classes to the HTML tags. This approach only works if the template is using Google Code Prettify for syntax highlighting. We should allow users to override the built-in highlighter function so that it's possible to use other syntax highlighters and highlight code at the time the docs are generated.

There are a few ways we could implement this feature:

  • Allow the user to specify a highlight function in a JS config file. This forces people to use a JS config file (but maybe that's not a bad thing).
  • Allow the user to specify the location of a module that exports a highlighter function. This would be more cumbersome than the previous approach, but it would work with JSON config files. We could do this in conjunction with the previous approach.
  • Allow the user to specify a format string for the code wrapper. This is probably not flexible enough.
  • Allow the template to export a highlight function. This would require JSDoc to load the template before it could do anything Markdown-related, so this is a non-starter.
@hegemonic hegemonic added this to the 3.6.0 milestone Jul 22, 2017
@hegemonic
Copy link
Contributor Author

hegemonic commented Jul 23, 2017

Fixed on master. Users can now do either of the following:

  • Assign a highlighter function to markdown.highlight in a JS config file.
  • Specify the path to a highlighter module in markdown.highlight in a config file. The highlighter module should export a method called highlight. (This module could be the publish.js file for a JSDoc template.)

Either way, the highlighter function should look like function highlight(code, language) {}, where code is the contents of the code block and language is the language the user specified, if any. The highlighter function should escape the code block's contents and wrap them in <pre><code> tags.

lheberlie added a commit to bsvensson/jsdoc that referenced this issue May 2, 2019
* master: (95 commits)
  update dependencies and supported Node.js versions
  3.5.5 changelog
  Prefer copyFileSync from here over native (jsdoc#1440)
  upgrade Babylon
  fix test breakage
  3.5.4 changelog
  prevent crash when an anonymous class is passed as a parameter (jsdoc#1416)
  hide the signature in the heading for classes with hidden constructors (jsdoc#1397)
  chore(package): update nyc to version 11.1.0 (jsdoc#1417)
  add `templates.useShortNamesInLinks` config option (jsdoc#738)
  allow users to specify a highlighter for Markdown code blocks (jsdoc#1412)
  document `longnamesToTree`, plus other doc improvements (jsdoc#43)
  move namespaces and interfaces up in the nav (jsdoc#1410)
  don't pretty-print code blocks that begin with "```plain" (jsdoc#1361)
  improve comment
  make the `exports` tag work correctly when combined with the `enum` tag (jsdoc#970)
  fix Node.js 4.x
  update tested Node.js versions
  use the markdown-it Markdown parser by default (jsdoc#1243)
  enable more Babylon options (jsdoc#1411)
  ...

# Conflicts:
#	.travis.yml
#	README.md
#	lib/jsdoc/src/astbuilder.js
#	lib/jsdoc/src/visitor.js
#	lib/jsdoc/util/markdown.js
#	lib/jsdoc/util/templateHelper.js
#	package.json
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

1 participant