theskumar / autolink-references-mkdocs-plugin Goto Github PK

Assuming the following initial markdown:

Lorem ipsum dolor sit amet, consetetur PROJ-1234 sadipscing elitr

My expectation is, that the plugin automatically transforms the above text to something like:

Lorem ipsum dolor sit amet, consetetur [PROJ-1234](https://jira.mycorp.com/browse/PROJ-1234) sadipscing elitr

But instead everything after the issue reference in the line is deleted:

Lorem ipsum dolor sit amet, consetetur [PROJ-1234](https://jira.mycorp.com/browse/PROJ-1234)

As far as I can tell, the currently constructed regex is for example:

[\[]?PROJ-([0-9]+)[\]]?(\(?.*\)?)

I think that the part of the regex that should match the round brackets and the original markdown link is wrong as it matches not only the round braces and the link but instead everything in the same line after the reference. See here for an explanation.

My suggestion is to change it to

\[?PROJ-([0-9]+)\]?(\([^)]*\))?

as this will match only the reference and optionally the surrounding markdown link. See here for an explanation.

_{Andreas Tetzner <[email protected]> on behalf of Daimler TSS GmbH. Provider Information.}

attr_list extensions is used by multiple mkdocs themes, and possibly incompatible with this plugin

Let's say we want to link to header anchors:

  - autolink_references:
      autolinks:
          - reference_prefix: F-
            target_url: /features#F-<num>

And those anchors we want to add manually with attr_list extension:

## Feature 1 { #F-001 .class-feature }

Lorem ipsum ...

## Feature 2 { #F-002 .class-feature }

Lorem ipsum ...

This plugin will break the attr_list tag by changing it to something like:

## Feature 2 { #[F-002](/features#F-002) .class-feature }

And as a result:

• attr_list will not be recognized and will be injected into the content creating ugly "Feature 2 { F-002 " header
• header ID will be auto-generated from title as #feature- and therefore, auto-links will not work

Please, add a feature to skip attr_list tags when attr_list is enabled.

Link to attr_list extension and syntax: https://python-markdown.github.io/extensions/attr_list/

Thanks for your work and this plugin, very useful.

mkdocs.yml:

  autolink_references:
    autolinks:
      - reference_prefix: '#'
        target_url: "https://github.com/USER/PROJECT/issues/<num>"

which it's quite intuitive that this turns on a lot of conflicts.
So the questions are:

• is there an alternative to avoid problems with anything in the docs? I can't use the form <user>/<project>#<num>
• can be applied a filter for specific folders/files where it is enabled to work?
  E.g. I need it only to work in docs/news/ directory, where I mention the issues only in the application' release posts:

  autolink_references:
    autolinks:
      - sources:
        - "docs/PROJECT1/news/"
        - "docs/PROJECT1/changes.md"
        target_url: "https://github.com/USER/PROJECT1/issues/<num>"
        reference_prefix: '#'
      - sources:
        - "docs/PROJECT2/news/"
        - "docs/PROJECT2/changes.md"
        target_url: "https://github.com/USER/PROJECT2/issues/<num>"
        reference_prefix: '#'

The plugin incorrectly transforms reference-style links.

For example this input

[TEST-123][some-id]

[some-id]: https://jira.com/some-org/TEST-123

Gets transformed to this

[TEST-123](https://jira.com/some-org/TEST-123)[some-id]

[some-id]: https://jira.com/some-org/[TEST-123](https://jira.com/some-org/TEST-123)

Which renders as

TEST-123some-id

I was able to reproduce the behavior in Regexr here: https://regexr.com/6jtik
You can see the incorrect matching in this screenshot: