Python code is here:
https://github.com/boostorg/website-v2/blob/develop/core/markdown.py

@vinniefalco What is boostlook? CSS that's already applied or something that needs to happen to the asciidoc itself?

The markdown rendering is doing some stuff that might be lost in this process:

• Rendering code blocks with the solarized color scheme
• Rendering youtube links as iframes

BoostLook is the name of a tool which styles the HTML generated by Asciidoctor and Antora, to give them a distinct and consistent look and feel. This is the repository:
https://github.com/boostorg/boostlook

The look is achieved by enclosing conforming HTML in a div with class="boostlook".

As for code blocks and youtube embeds, we will need to understand how to express that in Asciidoc markdown. I believe code blocks are already handled. Not sure about the yt embeds.

This page might prove helpful: https://docs.asciidoctor.org/asciidoc/latest/macros/audio-and-video/

@rbbeeston @vinniefalco

What is the motivation for this?

kramdoc doesn't convert our youtube embeds:

kramdoc - << EOF 
[[ youtube | U4VZ9DRdXAI ]]
EOF

output:

[cols=2*]
|===
| [[ youtube
| U4VZ9DRdXAI ]]
|===

That gets converted into a table by asciidoctor. I could do a regex substitution and replace instead before passing to kramdoc? I think that would be buggy and also convert youtube shortcodes in code blocks which would be wrong.

I don't see any references to boostlook in this repo.

If we go down the regex path, this is how asciidoctor wants youtube embeds: https://docs.asciidoctor.org/asciidoc/latest/macros/audio-and-video/#vimeo-and-youtube-videos

Okay, I think before we get too deep in this we need to first manually port an .md file to adoc. The file should have the elements in question. So we should convert this one:

https://raw.githubusercontent.com/boostorg/beast/refs/heads/develop/README.md

Then once we agree on the conversion it should be more straightforward to write a script to automate that. Thoughts?

Looking at the README.md for beast, there are no youtube embeds. It is just an image with a hyperlink. Can we do a straight conversion and keep it that way for now? Is there another Boost library that has an actual youtube embed in the README.md ?

Just following up on this. We can do this if that’s what you want. I’m not sure if there’s a boost library that has an actual youtube embed in the README.me. If we don’t need to support youtube videos then we can do this. Otherwise, let’s check in on this.

cc @rbbeeston

A straight conversion can't possibly be wrong. If we want more, we can consider that later

@vinniefalco

A straight conversion can't possibly be wrong.

Markdown is a nightmare of a format with multiple incompatible dialects. Mistletoe, the current renderer, implements CommonMark. kramdown does not specify its dialect, but issues indicate it is not compatible with CommonMark: gettalong/kramdown#500

For example, consider this markdown document

header
header
------
text

mistletoe rendering:

<h2>header
header</h2>
<p>text</p>

kramdoc-asciidoctor | asciidoctor --embedded rendering:

asciidoctor: WARNING: : line 3: unterminated listing block

<div class="paragraph">
<p>header
header</p>
</div>
<div class="listingblock">
<div class="content">
<pre>text</pre>
</div>
</div>

The meaning has changed entirely! kramdoc doesn't interpret the ------ as a header and instead as an unterminated code block. It doesn't render a header, and the rest of the content in the document will be considered part of this code block.

Even when kramdoc doesn't interpret a symbol differently than CommonMark, it passes symbols through that would be literals in markdown but get processed and replaced by asciidoctor.

Here is a difference in rendering of the beast readme. Ignore the style differences, this is with no CSS. First markdown, then kramdoc|asciidoctor:

The pipe symbol in the text of the link gets interpreted as a table.

Now, assuming you want to continue down this path, I have some questions:

I see process_md used in two places: MarkdownTemplateView and Library.get_description. MarkdownTemplateView relies on frontmatter, while get_description strips and ignores it. Do you want both of these code paths to go through kramdown then asciidoctor? Do the markdown files processed by get_description actually have frontmatter that needs to be stripped?

pandoc is another converter that may give better results because it supports CommonMark

We only need to care about the dialect of markdown that GitHub uses

Rob decided that we would only modify get_description and not MarkdownTemplateView. Also, we will not support frontmatter in get_description. We'll look at the output and decide if anything more needs to be done.

I will experiment with pandoc to see if we get more usable results than kramdoc