Skip to content

Document tutorial card images #857

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bryantgillespie merged 1 commit into from
Oct 29, 2026
Merged

Document tutorial card images #857

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ Reusable content fragments live in `/content/_partials/` and are included via th
- `app/pages/[...slug].vue` — catch-all for content pages
- `app/pages/api/[tag].vue` — OpenAPI-generated API reference (spec comes from the `@directus/openapi` package via `scripts/generate-api-reference.ts`; fixes to endpoint docs belong in the [directus/openapi](https://github.com/directus/openapi) repo)
- `app/pages/tutorials/` — tutorial section with nested routes
- Tutorial card images are static files baked by `pnpm tutorial-cards` (see CONTRIBUTING.md, Tutorial Cards)

### Custom Markdown Components

Expand Down
15 changes: 14 additions & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,17 @@ navigation:
---
```

### Tutorial Cards

Tutorial cards show a logo for the first entry in `technologies`. The cards are static images in `public/img/tutorials/cards/<technology>.jpg`, baked from `public/img/tutorials/<technology>.png`. A technology without a logo gets the Directus card.

When a tutorial uses a technology that has no card yet:

1. Optionally add the logo as `public/img/tutorials/<technology>.png`. The file name must match the `technologies` value exactly.
2. Run `pnpm tutorial-cards` and commit the new card.

To rebuild every card (for example after changing a logo or the background), run `node scripts/tutorial-cards.ts --force`.

## Repository Tooling

The repository includes scripts that keep docs routes stable when files move and that index the docs into Typesense.
Expand All @@ -75,14 +86,16 @@ pnpm stable-ids:ensure # Add missing stableId frontmatter
pnpm stable-ids:check # Validate stableId frontmatter
pnpm redirects:sync # Update redirects.json for moved pages
pnpm redirects:check # Check redirect coverage without writing files
pnpm tutorial-cards # Bake missing tutorial card images
pnpm tutorial-cards:check # Check every tutorial has a card
pnpm index:docs # Build the search index in Typesense
pnpm typesense:cleanup-preview # Delete stale Typesense preview indexes
pnpm typecheck:scripts # Type check repository scripts
```

Stable IDs give each public docs page a permanent identity. Nuxt Content derives its unique page IDs from file paths, so moving a page changes its built-in ID. Redirect sync compares the current branch to `origin/main`, so moved pages keep their old URLs working.

CI runs `pnpm stable-ids:check` and `pnpm redirects:check` for docs changes.
CI runs `pnpm stable-ids:check`, `pnpm redirects:check`, and `pnpm tutorial-cards:check` for docs changes.

- New docs page: run `pnpm stable-ids:ensure`, then commit the new `stableId`.
- Moved docs page: keep the existing `stableId`, run `pnpm redirects:sync`, then commit `redirects.json`.
Expand Down
Loading