Need help with cross references, formatting in tables, conditional text, and variables.

[stoobie]

I investigated Markdown in mkdocs-material vs AsciiDoc last week, and I was able to get near parity regarding industry-standard tech writing features, including include files, conditionals, advanced formatting, and variables.

Can anyone help overcome the following difficulties? Or are these issues not overcomable?

• cross references: I could not find any comparable functionality to xrefs in AsciiDoc.
  xrefs are great for several reasons. 2 that jump to mind are:
  1. They resolve automatically, so you can put xrefs in snippets and it doesn't matter where you put the snippet in the dir tree hierarchy, the xref resolves correctly.
  2. The title of the target pages automatically populates the xref text if you leave it blank, which can be great for avoiding inaccurate link text if you update the target page's title.
• How do I define and use conditions and variables? I know that I have to edit the main.py file to add variables and define conditions, so that I can later use conditional text and insert variables, but I can't find info on how to edit main.py, and I can't find info on how to implement conditional text once I've set it up in main.py, either globally or per topic.
• Tables--How do format text in table cells, like bold, italics, lists...in other words normal markdown formatting?

[kamilkrzyskow]

Hi @stoobie,

the cross-reference was answered by yourself in the sibling discussion, please keep the discussions cross-referenced in the future as well ;]

• Is there a way to use cross references instead of links? #8281

As for the other two:

How do I define and use conditions and variables? [...]

main.py does ring a bell when it comes to the macros plugin, but you haven't really specified it, so I'm not sure. The plugin adds "Jinja processing" to the Markdown files itself, so you can add conditionals in the Markdown files the same way as you'd do in Jinja2 templates.

https://jinja.palletsprojects.com/en/stable/templates/#if

The only thing that's different is the context, as IIRC the macros plugin can use config.extra and the page.meta values directly.
Therefore, extra could be used as a global container, and everything else would be local.

https://mkdocs-macros-plugin.readthedocs.io/en/latest/#variables
https://mkdocs-macros-plugin.readthedocs.io/en/latest/pages/#configuration-variables

But maybe you don't want to add custom Jinja syntax to your Markdown files to keep them compatible with editors etc.
Then, I would recommend to use hooks to add logic for replacing placeholders etc. in the on_page_markdown event.

Tables--How do format text in table cells, like bold, italics, lists...in other words normal markdown formatting?

To format tables as Markdown, use Markdown syntax for them.

• Support alternative table formats in markdown #5677

Or if you really prefer to use <table> then enable the md_in_html extension and for every opening block-level HTML tag in the tree structure, add a markdown attribute <table markdown><td markdown> etc. Also keep the HTML tree structure, flat, add no indents, as in Python Markdown indents are handled specially.

[kamilkrzyskow]

Errata: As mentioned here #8353 (reply in thread)
Only block-level HTML tags need to use markdown, a list of theme can be found here:

• https://python-markdown.github.io/extensions/md_in_html/#markdown1

So td can omit the markdown attribute.