Merge pull request #3763 from dannon/content-migration

Normalize legacy content syntax at the source

Author: dannon

.github/workflows/main.yml

@@ -53,6 +53,26 @@ jobs:
       - name: Validate metadata
         run: uv run --python 3.12 --with pykwalify --with pyyaml make validate-metadata
 
+  content-lint:
+    name: Content Lint
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: .
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: astro/package-lock.json
+
+      - name: Lint content
+        run: cd astro && npm ci && npm run content:lint
+
   unit-tests:
     name: Unit Tests
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -45,6 +45,10 @@ check: ## Format, lint, and test Astro site
 	cd astro && npm install && npm run format && npm run lint && npm test
 .PHONY: check
 
+content-lint: ## Lint content files for legacy syntax issues
+	cd astro && npm install && npm run content:lint
+.PHONY: content-lint
+
 link-check: build ## Build site and check internal links with linkinator
 	cd astro && npx astro preview --port 9999 & sleep 5 && cd astro && PORT=9999 npm run links:internal; kill %1 2>/dev/null || true
 .PHONY: link-check

Makefile

@@ -1,24 +1,26 @@
 # Galaxy Community Hub
 
-The [Galaxy Community Hub](https://galaxyproject.org) ↗️ is the community and documentation website for the [Galaxy Project](https://galaxyproject.org/use/)↗️. The Hub is maintained by the community through this GitHub repository. To update the Hub, (1) visit the [Hub "About" page](https://galaxyproject.org/hub/)↗️ and (2) view the links in this `README.md` file [Table of Contents](#table-of-contents).
+Source for the [Galaxy Community Hub](https://galaxyproject.org), the community and documentation website for the [Galaxy Project](https://galaxyproject.org). The site is built with [Astro](https://astro.build/) and content is written in Markdown. The Hub is maintained by the community through this GitHub repository.
 
-## About the Galaxy Project
+- **Galaxy Project**: https://galaxyproject.org
+- **Galaxy Server (usegalaxy.org)**: https://usegalaxy.org
+- **Galaxy Training Network**: https://training.galaxyproject.org
+- **GitHub Issues**: https://github.com/galaxyproject/galaxy-hub/issues
 
-To learn more about the Galaxy Project, visit the [Hub "Home" page](https://galaxyproject.org)↗️.
+## Contributing
 
-## Table of contents
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add or edit content, and the [Contributing](https://galaxyproject.org/hub/contributing/) page on the Hub itself.
 
-1. Structuring Content, Files, and URLs
-    1. [Markdown](content/hub/contributing/markdown/index.md) - How to format paragraphs and images
-    2. [File Organization and URLs](content/hub/contributing/file-organization/index.md) - How to name files and structure URL paths
-    3. [Static and Dynamic Pages](content/hub/contributing/file-organization/index.md#static-pages) - How to display list of pages, custom layouts, and categorized pages
-    4. [Subsites](content/hub/global/index.md) - How to access existing subsites or start your own Hub subsite
-2. Contributing Content, Images, and Code (multiple options to publish changes)
-    1. [[Option 1] Editors](content/hub/contributing/index.md#option-1) - Do it all in Github
-    2. [[Option 2] Developers](content/hub/contributing/index.md#option-2) - Clone the repository (and run in your local environment)
+## Quick reference
+
+- **Content directory**: [`/content/`](/content/) — all Markdown content lives here
+- **Astro site**: [`/astro/`](/astro/) — site source code, build scripts, components
+- **Dev server**: `make dev` → http://localhost:4321
+- **Build**: `make build`
+- **All targets**: `make help`
 
 ## License
 
-The [contents](/contents/) of the Galaxy Hub are licensed under the [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0).
+The [contents](/content/) of the Galaxy Hub are licensed under the [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0).
 
-The code behind the infrastructure is licensed under the [MIT License](LICENSE.md)
+The code behind the infrastructure is licensed under the [MIT License](LICENSE.md).

README.md

@@ -1,74 +1,90 @@
-# Galaxy Community Hub - Astro Migration
+# Galaxy Community Hub — Astro Site
 
-This is the Astro-based implementation of the Galaxy Community Hub, migrating from the existing Gridsome setup.
+The Astro-based Galaxy Community Hub at [galaxyproject.org](https://galaxyproject.org). Content lives in `/content/` at the repo root and is preprocessed into `src/content/` (gitignored) during build.
 
 ## Development
 
 ```bash
-# Install dependencies
+cd astro
 npm install
-
-# Start dev server (http://localhost:4321)
-# Automatically preprocesses content, generates redirects, and builds search index
-npm run dev
+npm run dev          # http://localhost:4321
 ```
 
+The dev command preprocesses content, generates redirects and search index, then starts the dev server with hot reload.
+
 ## Building
 
 ```bash
-# Build for production
-npm run build
-
-# Preview production build
-npm run preview
+npm run build        # full production build
+npm run preview      # serve the built site locally
 ```
 
 ## Code Quality
 
 ```bash
-# Run ESLint
-npm run lint
-
-# Fix auto-fixable lint issues
-npm run lint:fix
-
-# Check formatting
-npm run format:check
-
-# Fix formatting
-npm run format
+npm run lint && npm run format:check   # check
+npm run lint:fix && npm run format     # fix
+npm run content:lint                   # check content normalization
 ```
 
 ## Testing
 
 ```bash
-# Run Playwright tests
-npm run test
+npm run test              # Playwright E2E (starts dev server automatically)
+npm run test:ui           # Playwright with interactive UI
+npm run test:unit         # Vitest unit tests
+npm run test:unit:watch   # Vitest in watch mode
+```
+
+## Content and MDX
 
-# Run tests with UI
-npm run test:ui
+Content files are plain markdown by default. Files that use interactive components (like `<Icon>`, `<VegaEmbed>`, `<Twitter>`, etc.) must opt in to MDX processing by adding `components: true` to their frontmatter:
 
-# Run unit tests
-npm run test:unit
+```yaml
+---
+title: My Page
+components: true
+---
 ```
 
+Without this flag, component tags will not be rendered. The `npm run content:lint` command (also part of `--check` mode in normalize-content) will flag files where the flag is out of sync with actual component usage.
+
+### Available components
+
+Icon, VegaEmbed, Twitter, Mastodon, VideoPlayer, Carousel, Flickr, Supporters, Contacts, MarkdownEmbed, CalendarEmbed, Insert.
+
+### MDX compatibility
+
+Since MDX files are parsed as JSX, a few things that work in plain markdown will break in MDX:
+
+- **HTML comments**: Use `{/* comment */}` instead of `<!-- comment -->`
+- **Bare `<>`**: Use `&lt;&gt;` instead
+- **Angle brackets before numbers/dashes**: e.g. `<500` or `<---` need escaping
+
+These only matter in files with `components: true`. Plain markdown files are unaffected.
+
+## Build Pipeline
+
+Content preprocessing (`src/build/preprocess.mjs`) reads from `/content/` and writes to `src/content/`:
+
+1. Files are sorted into collections (articles, events, news, platforms, bare-articles, inserts)
+2. Legacy syntax is converted (kramdown attributes, old Gridsome tags)
+3. Slugs are normalized (camelCase split, underscore→hyphen, lowercase)
+4. Images are copied to `public/images/{slug}/` and paths rewritten
+5. Files with `components: true` become `.mdx`; everything else stays `.md`
+
 ## Project Structure
 
 ```
 astro/
 ├── src/
-│   ├── components/     # Vue and Astro components
-│   ├── layouts/        # Page layouts (Article, Home, Platform, etc.)
+│   ├── build/          # Preprocessing, normalization, search index
+│   ├── components/     # Vue 3 and Astro components
+│   │   └── mdx/        # Components available in MDX content
+│   ├── layouts/        # Page layouts
 │   ├── pages/          # File-based routing
-│   ├── styles/         # Global CSS
+│   ├── styles/         # Global CSS (Tailwind 4)
 │   └── content.config.ts
-├── public/             # Static assets
-└── content/            # Symlinked from parent (news, events, etc.)
+├── public/             # Static assets (images copied here during build)
+└── tests/              # Playwright E2E tests
 ```
-
-## Notes
-
-- This is a parallel development effort - the existing Gridsome site remains unchanged
-- Content is shared with the parent directory via symlinks
-- Uses Tailwind CSS with Galaxy brand colors
-- Vue 3 components for interactive elements

astro/README.md

@@ -23,18 +23,20 @@
     "lint": "eslint . --ext .js,.mjs,.ts,.vue,.astro",
     "lint:fix": "eslint . --ext .js,.mjs,.ts,.vue,.astro --fix",
     "format": "prettier --write 'src/**/*.{js,mjs,ts,vue,astro,css}'",
-    "format:check": "prettier --check 'src/**/*.{js,mjs,ts,vue,astro,css}'"
+    "format:check": "prettier --check 'src/**/*.{js,mjs,ts,vue,astro,css}'",
+    "normalize": "node src/build/normalize-content.mjs",
+    "content:lint": "node src/build/normalize-content.mjs --all --check"
   },
   "dependencies": {
     "@astrojs/mdx": "^4.3.13",
     "@astrojs/rss": "^4.0.15",
     "@astrojs/sitemap": "^3.7.0",
     "@astrojs/vue": "^5.1.4",
+    "@citation-js/core": "^0.6.9",
+    "@citation-js/plugin-bibtex": "^0.6.9",
     "@fontsource/atkinson-hyperlegible": "^5.2.8",
     "@nanostores/vue": "^1.0.1",
     "@sindresorhus/slugify": "^2.2.1",
-    "@citation-js/core": "^0.6.9",
-    "@citation-js/plugin-bibtex": "^0.6.9",
     "@tailwindcss/typography": "^0.5.19",
     "@tailwindcss/vite": "^4.1.17",
     "@vueuse/core": "^14.1.0",
@@ -43,6 +45,7 @@
     "clsx": "^2.1.1",
     "glob": "^13.0.0",
     "gray-matter": "^4.0.3",
+    "lucide-static": "^0.575.0",
     "lucide-vue-next": "^0.555.0",
     "marked": "^17.0.1",
     "nanostores": "^1.1.0",
@@ -71,10 +74,10 @@
     "eslint-plugin-astro": "^1.2.0",
     "eslint-plugin-vue": "^9.28.0",
     "fast-xml-parser": "^5.4.1",
+    "linkinator": "^6.1.2",
     "prettier": "^3.3.0",
     "prettier-plugin-astro": "^0.14.0",
     "tw-animate-css": "^1.4.0",
-    "linkinator": "^6.1.2",
     "vitest": "^4.0.15"
   }
 }