Some .md files have preview problems

[mehmetdogru]

Checklist

• I've read the contribution guidelines.
• I've searched other issues and no duplicate issues were found.
• I'm convinced that this is not my fault but a bug.

Description

Usage of <figure markdown> and <figcaption> tags in some .md files like shown below causes visual problems since it is not parsed correctly.

<figure markdown>
  ![example](docs/crosswalk/example.png){width=1000}
  <figcaption>crosswalk module</figcaption>
</figure>

The files have this problems are:

• crosswalk-design.md
• stop-line-design.md
• detection-area-design.md
• virtual-traffic-light-design.md
• obstacle_stop_planner/README.md

Expected behavior

The pictures should be visible

Actual behavior

The pictures are not visible.

Steps to reproduce

1. Go to any page addressed in the description e.g.
2. Observe that there are some pictures are not visualized. (Check raw code e.g.)

Versions

No response

Possible causes

Usage of <figure markdown> and <figcaption> tags in md files

Additional context

No response

[mehmetdogru]

@xmfcx @kenji-miyake Could you take a look at this?

[kenji-miyake]

@mehmetdogru The docs aren't for GitHub preview but MkDocs Material.
They use this feature: https://squidfunk.github.io/mkdocs-material/reference/images/#image-captions

For now, could you see https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/crosswalk-design/ instead?

However, we can consider improving the notations to support both GitHub and MkDocs Material.

[kenji-miyake]

cc @satoshi-ota Please comment on this if you have any ideas. 🙏

[satoshi-ota]

[background]

Previously, I tried to align center by using html tags as follows, but it is not able to shown in github.io pages because of incorrect converting of the relative image path. As far as I know, if we use html tags as follows, the absolute paths parse like /autoware.universe/planning/behavior_velocity_planner/crosswalk-design/docs/crosswalk/hoge.svg and includes unnecessary directory crosswalk-design. So, I use Mkdocs Material.

<div align="center">
  <img src="docs/crosswalk/hoge.svg">
</div>

[xmfcx]

Is it possible to have link in the universe .md pages to the corresponding universe documentation? Maybe created by the tool that creates documentation?

[kenji-miyake]

(Note: This comment is wrong.)

@xmfcx I think it's possible with mkdocs-macros. Just write {{ page }} and add some conversion.
https://mkdocs-macros-plugin.readthedocs.io/en/latest/macros/

[kenji-miyake]

Ah, no. We can't write it in Markdown files. lol
Sorry, please forget about it.

[kenji-miyake]

So, I think the only way is to write the documentation URL manually, but it takes some effort.

[mitsudome-r]

@mehmetdogru Are there any issues remaining in this issue? If not, I will close this issue.

[xmfcx]

Using https://autowarefoundation.github.io/autoware.universe/main/ it should be ok, I will close this issue.