Giters

traefik / structor

[Messor Structor 🐜] Manage multiple versions of a Mkdocs documentation

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Incompatible with custom_fences

KevinRoebert opened this issue · comments

commented

Hello, we would like to set a markdown_extensions.pymdownx.superfences.custom_fences for our MkDocs, but unfortunately, it is not applied correctly. In our example, the mermaid environments are not rendered correctly anymore.

The corresponding setting can be found here: https://github.com/drasyl-overlay/drasyl/blob/master/docs/mkdocs.yml#L75

You can simply reproduce this behavior with these steps:

  1. git clone https://github.com/drasyl-overlay/drasyl.git
  2. cd drasyl/docs
structor --owner="drasyl-overlay" --repo-name="drasyl" \
            --rqts-url="https://raw.githubusercontent.com/drasyl-overlay/drasyl/master/docs/requirements.txt" \
            --dockerfile-url="https://raw.githubusercontent.com/drasyl-overlay/drasyl/master/docs/docs.Dockerfile" \
            --menu.js-url="https://raw.githubusercontent.com/drasyl-overlay/drasyl/master/docs/theme/structor-menu.js.gotmpl" \
            --exp-branch=master --force-edit-url --debug
  1. Start a server e.g. http-server
  2. Visit page: http://127.0.0.1:8080/architecture/diagrams/
  3. Diagrams not rendered

If you try the same with mkdocs build or mkdocs serve the diagrams are rendered.

commented

Hello,

Have you tried to build your doc through your Docker image?

commented

Hello,

Have you tried to build your doc through your Docker image?

Sure, you could use the Makefile as a shortcut inside the docs folder. It is using the docs.Dockerfile.

If you run make docs or make docs-serve the diagrams are rendered correctly. The structure of the documentation is pretty much the same as it is in the traefik/traefik repo.

commented

it's related to the !!python syntax, the YAML parser that we use is not able to read those elements.

Could you try something like that:

format: '!!python/name:pymdownx.superfences.fence_div_format'
commented

Could you try something like that:

format: '!!python/name:pymdownx.superfences.fence_div_format'

Doesn't work. The marks breaks also the normal build with mkdocs.

commented

I'm not a specialist of YAML syntax but !! seems related to tag syntax, I don't know how this works.

commented

Ok. I've replaced the custom_fence with div tags. As readthedocs/readthedocs.org#6889 and facelessuser/pymdown-extensions#892 states, there is no real workaround if the YAML parser does not support !!python object creation.

commented

I found a workaround for the parser, I need to do some tests, but it's 3 am for me, so I will do that tomorrow.

commented

I created a fix 2623be0

commented

Fixed in v1.11.1

commented

It works. Thanks a lot 👍

commented

@ldez You have made a small mistake with the assets for version 1.11.1. There the checksums.txt must not contain a v for the version, otherwise your godownloader.sh cannot download the file anymore.

$ curl -sfL https://raw.githubusercontent.com/containous/structor/master/godownloader.sh | sudo bash -s -- -d -b $GOPATH/bin v1.11.1
traefik/structor info checking GitHub for tag 'v1.11.1'
traefik/structor debug http_download https://github.com/traefik/structor/releases/v1.11.1
traefik/structor info found version: 1.11.1 for v1.11.1/linux/amd64
traefik/structor debug downloading files into /tmp/tmp.SssnTW5Zrq
traefik/structor debug http_download https://github.com/traefik/structor/releases/download/v1.11.1/structor_v1.11.1_linux_amd64.tar.gz
traefik/structor debug http_download https://github.com/traefik/structor/releases/download/v1.11.1/structor_1.11.1_checksums.txt
traefik/structor debug http_download_curl received HTTP status 404
commented

oops, I will fix that