Generated anchor are not uniq about shins HOT 21 CLOSED

This is true. How are you generating the source markdown?

from shins.

With widdershins, from an openapi file

from shins.

And are you using custom templates? You need to ensure the link anchor ids are unique yourself, which you can do by replacing the clashing ## anchors with

# Authentication
<h2 id="authentication-default">Default</h2>

Please let me know if it's an anchor from a built-in template (or hardcoded) and I'll fix it.

from shins.

I am using the built-in templates, not custom ones :)

from shins.

OK, is 'Authorization' a tag in your OpenAPI definition? I'm not sure where '## Default' is coming from... They're not duplicated operationIds are they?

from shins.

I am converting multiples openapi files into one documentation.

#Authentication and #Authorization are the services names
I don't have an "Authorization" tag in my OpenAPI file.

I don't know why but widdershins create a "Default" tag with methods that don't need authentification (security tag), and a "Service name" tag with methods with auth, resulting in something like that:

# Invoices (service name)
## Default
### operationId1
### operationId2
### operationId3
## Invoives (service name)
### opeartionId4 (auth)
### operationId5 (auth)

from shins.

How are you converting the multiple OpenAPI definitions into one? How do the service names end up as level-one headers?

Widdershins creates a 'Default' tag for any operations which don't have a tag - this is so they have somewhere to go in the Table Of Contents (TOC). If you are pre- or post-processing the markdown to adjust the tags, you'll have to take this into account by modifying the Default tags to include the service name in the id property as above.

from shins.

I am converting each OpenAPI files with widdershins, then with a regex I remove markdown header, i convert # to ## and ## to ###.

Then I manually insert my header, and I join each converted markdown prefixed with # Service Name

Thanks for the tips about "Default" tag, I will add tags for methods that don't have ones in my openapi files

from shins.

Ok, now I think I understand! The problem is your script isn't making the duplicate # Default headers unique, but Widdershins doesn't know any 'service name' to use to make them unique either.

I think we have a few options:

• create an option for Widdershins to pass in a service-name for each OpenAPI definition
• use the info.title of the API (with spaces removed) as a prefix for the id property
• use an OpenAPI specification (vendor) extension like x-service-name
• use a guid or similar - has disadvantage it will change every time the conversion is run

Do you see other advantages/disadvantages to any of these?

BTW, are you using the new --headings option for Widdershins to enable <h3>s to appear in the TOC?

from shins.

I think the info.title is the easier / faster to implement

Yeah, I am using the --headings option on widdershins

from shins.

One other option is to make sure every operation in your OpenAPI definitions has a tag, and make the 'default' tags unique across all definitions...

from shins.

Ok - testing the change... Please consider adding your script / solution to the Widdershins wiki in case anyone else is working with micro-service definitions.

from shins.

Should be fixed in Widdershins v2.2.10 - please let me know if not.

from shins.

I am still getting the issue:

<h2 id="default">Default</h2>

from shins.

Also widdershins still create an empty "Default" section even if all paths get a tag field

from shins.

Hmm, I'm not seeing that with either the specs/petstore.json definition (where every operation has a tag) or specs/xkcd.yaml where 'Default' is included but the heading is now:

<h1 id="XKCD-default">Default</h1>

from shins.

Looks like it is a problem with the published package. When I pull master from widdershins "Default" id is ok, and not on 2.2.10

from shins.

Ok so, there is still a problem with h2 / h3 fields that have the same name:

# Authentication
### Health check
# Authorization
### Health check

Click on the second one "Heal check" will link to the first one

from shins.

The only difference between GitHub master and v2.2.10 was (what should have been) an unrelated commit. Anyway, I've published v2.2.11 now containing that commit.

If your OpenAPI definitions contain clashing tags, I think you need to do the replacement of the ## and ### headings with anchor tags in your script. If I do it for all TOC entries it will break peoples' bookmarks.

It will be easier to adjust the headings in v3.x of Widdershins, which should be released later this month.

from shins.

Thanks a lot :)

from shins.

Closing this here, as I think it is really a widdershins issue. Please feel free to carry on the conversation on Mermade/widdershins#61

from shins.