dbt-labs/hub.getdbt.com

dbt Hub README doesn't match the GitHub README format

fivetran-joemarkiewicz opened this issue · 6 comments

fivetran-joemarkiewicz commented

Overview of the Issue

We are making updates to our dbt package READMEs to streamline the onboarding experience for first time package users. One of the updates is including our optional package configuration steps within an expandable section of the README. It seems to be that this section is interpreted within GitHub, but it loses all formatting within the dbt Hub site. See the comparisons below:

Expected Outcome

The formatting and style within the dbt hub README matches that of GitHub

Additional Notes

I noticed a few other formatting options don't translate across as well. For example the badges are all centered on GitHub and are strangely formatted within the dbt hub.

I am happy to contribute if possible to address this issue. Thanks!

jasnonaz commented

Hi Joe! Thanks for letting us know about this. It looks like there is definitely something funky going on with the README import. I'm going to connect with folks internally and see if we can get a fix for this prioritized.

  • 👍1
fivetran-joemarkiewicz commented

Hi @jasnonaz has this been able to be looked at by chance?

dbeatty10 commented

@fivetran-joemarkiewicz @b-per fixed a piece of this in #1780 so the toggle arrows are showing correctly now:

https://hub.getdbt.com/fivetran/fivetran_log/latest/

  • image

Content without Markdown headings look good:

  • image

But those containing Markdown headings weren't fixed by this change:

  • image

There is some explanation in #1780:

This is still not 100% perfect, especially when special formatting is done within the details tag, but based on my troubleshooting, this is a limitation of kramdown, the MD renderer used in middleman. (Here is a demo of kramdown if someone wants to try specific behavior). But I feel that this is still a pretty big improvement compare to the current behavior.

As you mentioned, the badges show up stacked:

  • image

Rather than side-by-side and centered:

  • image
dbeatty10 commented

@fivetran-joemarkiewicz just merged another contribution from @b-per -- check it out!
https://hub.getdbt.com/fivetran/fivetran_log/latest/

image

fivetran-joemarkiewicz commented

@dbeatty10 you read my mind as I was just looking into this yesterday!

I just took a look at the expanding functionality looks great 🎉. I also agree with the above statement that while the badges still show as stacked, it is a huge improvement and allows for a good user experience. The stacking of the badges is minor in my opinion whereas the collapse issue was bigger.

With this, we will start leveraging the collapsable pieces into our README's. Thanks for your and @b-per help on this 🙏

  • 🎉1
dbeatty10 commented

Considering this resolved by #1780 and #1786.

@fivetran-joemarkiewicz we can open new issues if you run into other formatting issues.

  • 👍1