Anchors and Gitbook

Hi,

I’m using jsdoc-to-markdown to generate API docs in a Gitbook. It all works quite nicely except for anchors. Gitbook uses the id attribute for anchors instead of the name. However, just changing partials to use a different attribute doesn’t cut it because id attribute cannot use special symbols that jsdoc-to-markdown creates for its anchor names, e.g. + and . used for class instance and static methods. As a temporary workaround I’m using a small helper that replaces those special symbols with underscores:

exports.escapedAnchor = function (anchor) {
  if (typeof anchor !== 'string') return null;
  return anchor.replace('+', '__').replace('.', '_');
};

This does the trick, but I was wondering if this can be somehow addressed in the library. From what I can tell, changing those symbols here should suffice. However, If supporting Gitbook’s markdown isn’t a priority, I’ll try to create a dmd plugin for it.

[KevinAst]

@zandaqo … I successfully applied your work-around for the special characters fix. This was much appreciated, as jsdoc2md has not yet documented the --helper feature.

With this work-around, the id’s have been patched (ex: the dot '.' has been replaced with underbar '_'). However the {@link xyz} tags are still not working, as they still reference the dot. Is this the result of the the internal usage of anchorName (from mixes.hbs) that you mentioned?

As it turns out, this is not a big deal for me, because I am using a GitBook templating technique to do all my linking … replacing all usage of the {@link} tag. This allows me to seamlessly link between the Dev Guide and my API (and vice versa).

SideBar: Don’t know what your experience was like in fully integrating Gitbook/JSDoc, but you may be interested in this article detailing my process: Integrating GitBook with JSDoc to Document Your Open Source Project. One of it’s topics is the linking technique that I mentioned (above).

Thanks again!

[zandaqo]

@KevinAst You are actually right, I was getting my info on id from HTML 4 and didn’t notice the changes in HTML5. If memory serves, in days of old, DOM used ids as object property names somewhere, and since then JS devs try to avoid special characters in ids, well, at least I do. Thanks for correcting!

I guess we do have a reason to bother Gitbook with this issue then.