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.

Sign up for GitHub

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

Jump to bottom

Anchor with id rather than name #122

Closed
KevinAst opened this issue Apr 11, 2017 · 3 comments
Closed

Anchor with id rather than name #122

KevinAst opened this issue Apr 11, 2017 · 3 comments

Comments

@KevinAst
Copy link

KevinAst commented Apr 11, 2017 •
edited
Loading

I am using jsdoc-to-markdown (ver: 3.0.0) to document the API in my project: https://astx-redux-util.js.org/1.0.0/.

For some reason, jsdoc2md creates anchors using name <a name="ref">, instead of id <a id="ref". As far as I know, the id is required by Markdown (and html for that matter) in order to link to it.

My current process applies a fix by overriding the header.hbs handlebar partial, changing name= to id= (you can see it at tooling/docs/header.hbs), however this seems like it should not be necessary.

This seems so basic that I can't believe it is a bug. Am I missing something?

Your help is greatly appreciated.

BTW: Great Library!
@75lb
Copy link
Member

75lb commented Apr 12, 2017

hi! yes, it's because jsdoc2md output is primarily viewed on Github (in readme and API docs). Github has a whitelist for which attributes are respected in markdown source and id is not one them (id attributes get stripped). So, i used name which produced a working link in most browsers. But it's not always useful in environments other than Github, as you discovered.

In your case, tweaking the header partial was the best idea.

@75lb 75lb closed this as completed Apr 12, 2017
@KevinAst
Copy link
Author

Thanks for the quick reply! This gives me more insight into your dilemma (i.e. so many markdown parsers).

When you say that Github flavored markdown strips the id attribute, would there be anything wrong with supplying both the name and id attributes? This approach may accommodate more environments without the need to override partials.

Thoughts?

FYI: You may be interested in my docs site.

  • I am promoting a very polished set of docs using Gitbook, while still relying on my embedded JSDoc comments for the API - thanks to your jsdoc-to-markdown utility.
  • I know your primary thrust is Github-based readmes/apis, but this takes it a step further!
  • I have created a comprehensive gist that details how I accomplished this.
  • If you think this info is valuable, feel free to promote it in your site.

Thanks again for the great library!

@75lb
Copy link
Member

75lb commented Apr 12, 2017

When you say that Github flavored markdown strips the id attribute..

not GFM, Github (as in github.com) strips the id.
https://github.com/github/markup

I will investigate leaving the id attribute in but for now, because it's not something that's been requested before, i think your tweaked header partial makes most sense.

@75lb 75lb mentioned this issue May 1, 2017
Closed
S0AndS0 added a commit to S0AndS0/dmd that referenced this issue Jul 7, 2019
@S0AndS0
Changes anchorName to link headings by ID
45602b1 
This may address jsdoc2md/jsdoc-to-markdown#122 and 
jsdoc2md/jsdoc-to-markdown#125


Tests with MarkDown rendering on GitHub show that, heading text is 
striped of most non-letter and non-number characters (underscores and 
hyphens seem to remain), plus letters are lowercased, leading and 
trailing spaces are trimmed, duplicate spaces are treated as one and, 
spaces are turned into hyphens...


```JavaScript
const test_string = '(2; muc{hTi   me  @# t[h)e k3b]Oa}rd?';

const id_string = test_string.toLowerCase()
                             .replace(/[^a-z0-9_ ]/g, '')
                             .replace(/ +/g, '-');


console.log('id_string -> ' + id_string);
//> 2-muchtime-the-k3board
```


... above code-block _should_ replicate the stripping that happens 
automatically and allow for removal of `<a name="{{{anchorName}}}"></a>` 
from the `partials/all-docs/header.hbs` file.


> Note while show within the changes for this commit it is **not** 
suggested to merge `partials/all-docs/header.hbs` file changes.


Changes made to `anchorName` function (within the `ddata.js` file), 
reused as much code from elsewhere within the code base. And so far 
seems to operate correctly regardless of _`backticks`_ option.


To enable this new branch in logic set `id-headings` to `true` within 
configurations, eg...


**`package.json` _snippet_**


```JSON
{
  "jsdoc2md": {
    "name-format": "backticks",
    "id-headings": true
  }
}
```


... because, default behavior likely should be preserved for those that 
are depending upon the `name` attributes.
@S0AndS0 S0AndS0 mentioned this issue Jul 7, 2019
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@75lb @KevinAst