Issues found in https://github.com/galaxyproject/galaxy-hub/pull/3763

[bgruening]

• astro/src/build/normalize-content.mjs is for checking I think, and it would be better to rename the script imho if its not for checking, it can be removed
• can astro/src/build/preprocess.mjs be removed now?
• I'm not really sure why components: true is needed, this can be inferred if we have a fixed set of components, isn't it?
• I don't understand why so much of the MD has been replaced by HTML in e.g. (content/bare/eu/usegalaxy/proteomics/index.md) Is that now an HTML file with fontmatter, or and MD file? The MD table still exists.
• I would prefer if content/bare/eu/usegalaxy/notices.md stays as it is, but I can revert that back after the fact.
• {/* <img class="img-fluid float-right" src="/community/sig/mass-spectrometry/GalaxyP_logo.png" style="width:200px;" alt="Logo for Galaxy mass spectrometry community."/> */} is this now the official comment style? why? this looks really a-typic
  • ok I see this is only true in MDX aka component files, so as soon as I want to use a fancy Icon, I'm bound to those restrictions.
  • as soon as I want to use an Icon I need to use HTML links and not markdown links. This feels annoying. Maybe we recommend our uses to simply copy emojis in? (e.g. this page content/tutorials/g101/index.md)
• https://github.com/galaxyproject/galaxy-hub/pull/3763/changes#r2864492111 it would be really nice to find a way to share those Icons, the GitHub Icon, RSS etc are so common they will probably be used a lot, just save the SVG as separate file and reuse?
• linkbox not mentioned in the CONTRINUTING.md file
• lets work a bit on content/hub/contributing/markdown/index.md or consolidate with CONTRIBUTING.md
  • add copy and paste examples for image position, left, right, center
  • copy and paste table
  • <- this json should be next to the md file I assume, link to example
  • maybe really write a news item, which announces the new Hub and has all those things as example included
• <a data-flickr-embed still exists?
• did we move all images to directly next to the index.md file? I remember that ./image/ folders have been supported back then, no?
• Is content/toolshed/contributions/ linked from somewhere? Should we move that to the news section with proper tags? Should we redo that and combine with Antons recent News pages?
• CONTRIBUTING.md is removing a lot of content, which I'm not sure is covered elsewhere, we should work on this file and bring everything back that is still useful

[dannon]

The content migration strategy: where we are and where we're headed

Thanks for the thorough review and for collecting all of this in one place — really helpful to have it laid out.

Several of these points touch the same underlying questions — why components: true, why not auto-detect, what's with JSX comments, why was HTML changed in some files — so let's step back a bit and look at the big picture.

The problem

The Hub has ~4500 content files accumulated over a decade across three build systems (Metalsmith, Gridsome, Astro). They contain framework-specific syntax — Font Awesome icons, Kramdown attributes, <g-link>/<g-image> tags, Vue bindings — alongside raw Bootstrap HTML with inline styles. Event pages are particularly heavy: <div class="card-deck"><div class="card border-info mb-3" style="min-width: 12rem;"> blocks copy-pasted between years, drifting each time.

Two problems follow from this:

1. Build complexity. The preprocessor had to convert all the legacy syntax at build time — hundreds of lines of transforms on every build, source files that didn't match what Astro actually processed, and bugs that were hard to trace.
2. Content maintainability. When someone wants to build a rich event page, they reverse-engineer Bootstrap HTML from another page. There's no shared vocabulary for "card" or "alert" — just copy-pasted divs that drift. (You flagged this yourself with the button/card comment on the PR — exactly right.)

What #3763 did: normalize syntax at the source

This PR tackled the first problem by running automated transforms over the content files themselves and committing the results — Font Awesome → Lucide icons, <g-link> → <a>, Kramdown → standard attributes, Vue bindings → plain HTML, and so on. This was a deliberate mass-migration pass over legacy content, and it let us delete ~200 lines of build-time transforms from the preprocessor. The source files now reflect what Astro actually processes.

Some of the conversions look awkward in individual files (HTML replacing Markdown inside <div> blocks, JSX comments, etc.) — those are fair observations. They're artifacts of normalization: MDX doesn't process Markdown inside HTML block elements, so when a file like proteomics/index.md needs components: true for its <Twitter> embed, the Markdown inside its <div> blocks had to become HTML. That's an MDX parser constraint, not a design choice.

Why components: true is explicit

Part of the simplification was replacing MDX auto-detection with explicit opt-in. The preprocessor previously scanned for component tags to decide the format (~60 lines of heuristics). The detection itself worked, but the consequences were the problem: a file that compiled fine would break when someone added an HTML comment during a routine edit, because it had been silently upgraded to MDX. Or a file with "problematic HTML" would get silently downgraded, losing its components.

Explicit opt-in makes the contract visible. The content:lint CI check catches files where the flag doesn't match actual usage, so nothing falls through the cracks. And for the vast majority of content — standard news posts, event announcements — you never need the flag at all. Just write Markdown.

What comes next: a component library

The second problem — content maintainability — is the next phase. Instead of copy-pasting Bootstrap HTML, authors would use semantic components:

<Card title="Registration">
  Early bird closes June 1

  [Register now](/register)
</Card>

Styling lives in one place. Design updates propagate everywhere. Contributors don't need to know Bootstrap classes. #3602 tracks this.

This is where components: true pays off. It's not just about <Icon> and <Twitter> — it's the door to a shared component library that prevents the styling drift and copy-paste maintenance problem from happening again. Rich pages opt into a toolkit with a single frontmatter flag, and the components handle the presentation.

For existing content, the semantic migration is incremental: leave archival content alone (the Bootstrap compat CSS keeps it rendering), convert on contact when someone's already editing a page, and proactively migrate high-traffic pages like the current GCC and community landing pages.

The syntax normalization from #3763 and the explicit MDX opt-in are the foundation. The next step is building out the component library so that new rich content is written with components from the start, and we stop accumulating raw HTML.