starred/markdownlint

Fork 0

mirror of https://github.com/DavidAnson/markdownlint.git synced 2026-04-25 17:26:22 +03:00

[GH-ISSUE #209] Superfences style code triggering MD046 #2027

New issue

Closed

opened 2026-03-07 20:03:49 +03:00 by kerem · 8 comments

kerem commented

2026-03-07 20:03:49 +03:00

Owner

Originally created by @homotechsual on GitHub (Jul 29, 2019).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/209

I've got some documentation code I'm working on automated testing for which belongs to the CiviCRM project.

We use MkDocs to build the content on our documentation site. As part of our automated testing we'd love to properly lint our documentation according to a style guide.

The issue we're facing is that the MkDocs Material theme we're using provides for a helpful admonitions feature and the superfences feature. With these tools we can nest code examples inside handy "highlight" boxes.

Unfortunately it appears that markdownlint is detecting these as indented code blocks and is therefore expecting all other code blocks to be the indented type rather than "fenced".

We'd love to resolve this without turning off the check for inconsistency as this is useful for us.

Example code:

!!! note "How much does performance improve with a specialized cache service?"
    The exact answer will depend on the use-case and environment. However, we can consider an example.

    This example relates to CiviCRM `5.6.alpha1` on a barebones, local Drupal 7 site and benchmarked the time it takes to render the "Event Info" page (`/civicrm/event/info?id=1`) with the [Apache "ab"](https://en.wikipedia.org/wiki/ApacheBench) command.  This sends a large number of HTTP requests and calculates the average response time.

    ``` bash
    $ ab -n 100 -c 3 'http://localhost/civicrm/event/info?id=1'
    ```

    With the default, pure-MySQL configuration, the mean response time was ~460ms.  With Redis, this decreased by ~60ms (~13%) to ~400ms.
    
    Note, though, the local copy of MySQL on this laptop is probably faster than a typical MySQL because it stores *everything* in ram-disk (rather than HDD or SSD). Compared to a typical, self-hosted MySQL, the Redis/Memcache advantage is probably wider.

Is there any chance at all that markdownlint would add support for the superfences style syntax?

Originally created by @homotechsual on GitHub (Jul 29, 2019). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/209 I've got some documentation code I'm working on automated testing for which belongs to the [CiviCRM](https://civicrm.org) project. We use [MkDocs](https://www.mkdocs.org/) to build the content on our [documentation site](https://docs.civicrm.org). As part of our automated testing we'd love to properly lint our documentation according to a style guide. The issue we're facing is that the MkDocs Material theme we're using provides for a helpful [admonitions feature](https://squidfunk.github.io/mkdocs-material/extensions/admonition/#types) and the [superfences feature](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/). With these tools we can nest code examples inside handy "highlight" boxes. Unfortunately it appears that markdownlint is detecting these as indented code blocks and is therefore expecting all other code blocks to be the indented type rather than "fenced". We'd love to resolve this without turning off the check for inconsistency as this is useful for us. Example code: ``` markdown !!! note "How much does performance improve with a specialized cache service?" The exact answer will depend on the use-case and environment. However, we can consider an example. This example relates to CiviCRM `5.6.alpha1` on a barebones, local Drupal 7 site and benchmarked the time it takes to render the "Event Info" page (`/civicrm/event/info?id=1`) with the [Apache "ab"](https://en.wikipedia.org/wiki/ApacheBench) command. This sends a large number of HTTP requests and calculates the average response time. ``` bash $ ab -n 100 -c 3 'http://localhost/civicrm/event/info?id=1' ``` With the default, pure-MySQL configuration, the mean response time was ~460ms. With Redis, this decreased by ~60ms (~13%) to ~400ms. Note, though, the local copy of MySQL on this laptop is probably faster than a typical MySQL because it stores *everything* in ram-disk (rather than HDD or SSD). Compared to a typical, self-hosted MySQL, the Redis/Memcache advantage is probably wider. ``` Is there any chance at all that markdownlint would add support for the superfences style syntax?

kerem

2026-03-07 20:03:49 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-07 20:03:50 +03:00

Author

Owner

@nschonni commented on GitHub (Jul 29, 2019):

Probably a duplicate of #207

@nschonni commented on GitHub (Jul 29, 2019): Probably a duplicate of #207

kerem commented

2026-03-07 20:03:50 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 29, 2019):

Agreed. I’d prefer to handle non-standard extensions via parser plugins. Per the other issue, there is already one for Admonitions (not sure about SuperFences). If those plugins parse into the expected structure, these custom styles should be handled reasonably by the library without extra effort.

@DavidAnson commented on GitHub (Jul 29, 2019): Agreed. I’d prefer to handle non-standard extensions via parser plugins. Per the other issue, there is already one for Admonitions (not sure about SuperFences). If those plugins parse into the expected structure, these custom styles should be handled reasonably by the library without extra effort.

kerem commented

2026-03-07 20:03:50 +03:00

Author

Owner

@homotechsual commented on GitHub (Jul 29, 2019):

That makes sense - with regards admonitions/superfences - can these markdownItPlugins be added in vscode-markdownlint ?

@homotechsual commented on GitHub (Jul 29, 2019): That makes sense - with regards admonitions/superfences - can these markdownItPlugins be added in vscode-markdownlint ?

kerem commented

2026-03-07 20:03:50 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 29, 2019):

They are used, but not exposed: github.com/DavidAnson/vscode-markdownlint@a05bf6e578/extension.js (L365)

Referencing custom packages (especially those that have dependencies) is tricky from a VS Code extension - as you might infer from the custom rule example: https://github.com/DavidAnson/vscode-markdownlint#markdownlintcustomrules

If there are popular, well-written plugins, I’m open to adding them by default (as with the math parser above).

@DavidAnson commented on GitHub (Jul 29, 2019): They are used, but not exposed: https://github.com/DavidAnson/vscode-markdownlint/blob/a05bf6e578aee90347fcde4bc6ea44dadd48ebe5/extension.js#L365 Referencing custom packages (especially those that have dependencies) is tricky from a VS Code extension - as you might infer from the custom rule example: https://github.com/DavidAnson/vscode-markdownlint#markdownlintcustomrules If there are popular, well-written plugins, I’m open to adding them by default (as with the math parser above).

kerem commented

2026-03-07 20:03:50 +03:00

Author

Owner

@homotechsual commented on GitHub (Jul 29, 2019):

It'd be great to add in the markdown-it-admonition package.

@homotechsual commented on GitHub (Jul 29, 2019): It'd be great to add in the markdown-it-admonition package.

kerem commented

2026-03-07 20:03:50 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 29, 2019):

Have you tried it and can you confirm that things work well with it? Can you please point to some example files that I could use to try this myself?

@DavidAnson commented on GitHub (Jul 29, 2019): Have you tried it and can you confirm that things work well with it? Can you please point to some example files that I could use to try this myself?

kerem commented

2026-03-07 20:03:51 +03:00

Author

Owner

@homotechsual commented on GitHub (Jul 29, 2019):

I'll do some more thorough testing tomorrow and give you some repro steps and a repo pointer.

@homotechsual commented on GitHub (Jul 29, 2019): I'll do some more thorough testing tomorrow and give you some repro steps and a repo pointer.

kerem commented

2026-03-07 20:03:51 +03:00

Author

Owner

@homotechsual commented on GitHub (Jul 29, 2019):

I'll post the above to the issue queue for DavidAnson/vscode-markdownlint.

Good to close this one I think?

@homotechsual commented on GitHub (Jul 29, 2019): I'll post the above to the issue queue for DavidAnson/vscode-markdownlint. Good to close this one I think?