Custom markdown elements for using in .md pages

[A3Bagged]

Hello, sorry if this has been implemented already but i couldn't find a fix. I did find the following:
#514 and #7451

---

Preview:

---

Example of a website im trying to copy a function from: Thulite

Here he uses a ordered list for setup steps, but the markdown is totally different and im trying to implement something like that.
I've tried and that just throws <p><steps></steps></p> above everything else.
It only worked when there was text directly next to <steps> without breaks.

Example markdown: Click here

<Steps>

1. Add a default (fallback) email address to `config/_default/params.toml`:

    ```toml title="params.toml"
    # defaultEmail
    defaultEmail = "[email protected]"
    ```

2. Add the following CSS to `assets/scss/common/_custom.scss`:

    ```scss title="_custom.scss"
    span.email b {
      display: none;
    }
    ```

3. Create shortcode file `layouts/shortcodes/email.html` with the following content:

    ```html title="email.html"
    {{- /* Set defaults and get args. */}}
    {{- $address := index .Params 0 | default site.Params.defaultEmail }}

    {{- /* Get parts. */}}
    {{- $addressParts := split $address "@" }}
    {{- $userName := (index $addressParts 0) }}
    {{- $rootDomain := (index $addressParts 1) }}
    {{- $rootDomainParts := split $rootDomain "." }}
    {{- $domainName := (index $rootDomainParts 0) }}
    {{- $topLevelDomain := (index $rootDomainParts 1) }}

    {{- /* Render. */}}
    <span class="email">
      {{- printf "%s@%s<b>.%s</b>.%s" $userName $domainName $domainName $topLevelDomain | safeHTML -}}
    </span>
    ```

    The shortcode gets the email address you provided — using the default email address if you didn’t specify one. Next, it splits the email address in parts — `userName`, `domainName`, and `topLevelDomain` — and renders the HTML.

</Steps>

Result:

This doesnt render a <steps> HTML Block at all but rather creates a <ol> list with a role and class applied.

Is this possible with Material? or has it been implemented through a markdown extension? (sorry if it is)

I tried adding:

<script type="text/javascript">
    document.registerElement('steps');
    customElements.define("steps", steps);
  </script>

But that is for custom HTML blocks that Thulite doesn't use and currently is not being procecced well in the .md file
unless its a small text like you would use <strong> and not for paragraphs. ie.

<Steps> This here works

But this doesnt
</steps>

Results in:

i've added a red background in css by: steps, .steps { background:red;} to debug

---

I do know that i can change <step> to <ol class="steps"> and style it in CSS but the page writing & markdown won't be used by me, i just do the coding. So using <steps> is easier for the user.

Sincerely, Chris

[kamilkrzyskow]

Hello @A3Bagged,
this kind of custom behaviour needs to be implemented as a separate Markdown extension / plugin. The example site you've provided was made with Astro a JavaScript-based site generator which supports JSX / MDX.

• mkdocs material to support MDX #3621

That's a completely different ecosystem. Additionally, Python Markdown is quite strict when it comes to formatting, and a new empty line typically means there is a new paragraph <p>.

Later in #7451 squidfunk noted there is hope in the future that Material would support such kind of thing, but it does not currently.

I'm unaware of any Markdown extensions which do the exact thing you want 🤔 You can check the catalog. Perhaps you could hack the implementation of the Neoteroi timeline extension.

Apart of an extension you could also try a plugin / hook which would modify the Makrdown and adjust the HTML formatting to match the strictness of the Python Markdown implementation.

I've done so in the latest_blog_posts plugin of the mkdocs-nype theme.
The code replaces a special token in the Markdown (could be <steps>) and then properly formats it for further Markdown processing with very strict Markdown/HTML snippets. Please don't mind the bit of spaghetti code as it survived multiple changes of specification / of my approach 😆 The result can be seen on the Nype brand site - Markdown source.

The plugin / hook approach is simpler to make imo, however it has to scan the Markdown content from scratch, so the "upper" performance is lower than that of an extension, which would work on tokens (I think 😅). iirc the plugin I mentioned only works on the homepage, so I never needed to worry about that.

[kamilkrzyskow]

You could also try the new blocks:

• https://facelessuser.github.io/pymdown-extensions/extensions/blocks/

I haven't used them myself, but it looks like it supports setting the tag name and supports Markdown inside + nesting 🤔
So I guess it could be used in this sort of scenario.

[A3Bagged]

You could also try the new blocks:

• https://facelessuser.github.io/pymdown-extensions/extensions/blocks/

I haven't used them myself, but it looks like it supports setting the tag name and supports Markdown inside + nesting 🤔

So I guess it could be used in this sort of scenario.

Awesome thanks! I'm researching and i think im coming closer. Im new to mkdocs and markdown so knowing what to look for is overwhelming 🤣 i didnfind an article on custom markdown tags. Does this work on mkdocs? I think as long as the .py file is in the site directory it should work? (Since i think material uses also custom markdown-extensions right?)

Is there a specific directory that you need to follow? (For example material has plugins etc in 'material' folder instead of root)

• chris

[kamilkrzyskow]

Normal Python import rules apply here. You can use the PYTHONPATH environmental variable to set it to ".", so it will always include the <current directory> you're currently running python / mkdocs serve from.

Then you can create a module, so basically a directory modulename with an empty __init__.py file inside it. You can add other files beside that init file like steps.py and later use modulename.steps in your markdown_extensions

The docs for the Insiders projects plugin have a brief mention of that approach as well:

• https://squidfunk.github.io/mkdocs-material/plugins/projects/?h=pythonpath#config.projects_config_transform

---

As for the mkdocs-material theme and material directory, it's all configured during pip install mkdocs-material with the pyproject.toml file

[A3Bagged]

Thanks for the detailed info 😄
I didnt use --pip install i think but pulled the repo using github desktop. Now i just copy to a new folder inside "github" in documente and rename the old to 'backup' before doing massive changes to the theme so that i can revert. Hopefully all goes well when using build once completed

[kamilkrzyskow]

After pulling the repository from GitHub, pip install is still required, but you install it from the directory, not the pypi package.