Skip to content

Commit d8956a0

Browse files
codecalmBartosz-Do
codecalm
and
Bartosz-Do
authored
Migrate preview and docs packages from Eleventy to Astro (#2694)
Co-authored-by: Bartek <xbartoszdobija@gmail.com>
1 parent 9820d11 commit d8956a0

1,274 files changed

Lines changed: 56342 additions & 36999 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/rules/docs.mdc‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
description: Tabler docs package rules (Astro, MDX documentation pages)
3+
globs: docs/**
4+
alwaysApply: false
5+
---
6+
7+
# Tabler docs (@tabler/docs)
8+
9+
## Development
10+
11+
When starting the dev server, use background mode:
12+
13+
```
14+
astro dev --background
15+
```
16+
17+
Manage the background server with `astro dev stop`, `astro dev status`, and `astro dev logs`.
18+
19+
## Documentation
20+
21+
Full documentation: https://docs.astro.build
22+
23+
Consult these guides before working on related tasks:
24+
25+
- [Adding pages, dynamic routes, or middleware](https://docs.astro.build/en/guides/routing/)
26+
- [Working with Astro components](https://docs.astro.build/en/basics/astro-components/)
27+
- [Using React, Vue, Svelte, or other framework components](https://docs.astro.build/en/guides/framework-components/)
28+
- [Adding or managing content](https://docs.astro.build/en/guides/content-collections/)
29+
- [Adding styles or using Tailwind](https://docs.astro.build/en/guides/styling/)
30+
- [Supporting multiple languages](https://docs.astro.build/en/guides/internationalization/)
31+
32+
## Writing documentation pages
33+
34+
Pages live in `pages/**/*.mdx`. Use the flat convention: leaf pages are `foo.mdx`; only pages with sub-pages use `foo/index.mdx` (both render as `/foo/`).
35+
36+
- Write in simple English: short sentences, common words, direct verbs (`Use`, `Add`, `Set`).
37+
- Component docs use singular naming in frontmatter and filename: `title: Card`, `card.mdx` (not `cards.mdx`).
38+
- Do not add meta authoring notes (e.g. "this snippet is copy-paste ready").
39+
40+
### Frontmatter
41+
42+
Static YAML only. Required keys plus the layout:
43+
44+
```yaml
45+
---
46+
title: Alert
47+
summary: Short one-sentence summary of what this component does.
48+
description: Practical description of when and why to use it.
49+
layout: '@shared/layouts/DocsMdxLayout.astro'
50+
---
51+
```
52+
53+
Optional: `bootstrapLink: components/alerts/` when the component extends a Bootstrap component.
54+
55+
### Examples
56+
57+
Import shared components after the frontmatter and wrap previews in `Example`:
58+
59+
```mdx
60+
import Example from '@shared/components/docs/Example.astro';
61+
import Alert from '@shared/components/Alert.astro';
62+
63+
<Example>
64+
<Alert type="success" title="Wow!" description="Your account has been saved!" />
65+
</Example>
66+
```
67+
68+
- Add 1-2 short sentences before each `Example` describing what the preview shows.
69+
- `Example` props: `hideCode` (visual-only preview), `code` (override the displayed snippet), `centered`, `vertical`, `column` (narrow ~25rem column), `raw` (no preview wrappers), `bg="dark"` (background), `height`, `codeOnly`.
70+
- Raw HTML in an `Example` slot is reserialized by MDX — keep example markup on single lines next to tags to avoid stray `<p>` wrapping.
71+
72+
### Structure
73+
74+
Recommended `##` section order: `Overview`, `Installation` (optional), `Variants` (components) or `Usage` (utilities/workflows), `Accessibility`, `Examples` (optional), `SCSS variables` (optional), `Migration notes` (optional). Keep heading hierarchy consistent (`##` then `###`), use stable descriptive headings.
75+
76+
### Checklist
77+
78+
- Documented classes exist in `core/scss/` sources; do not document internal-only or removed classes.
79+
- Interactive examples include accessibility attributes (`aria-label`, semantic markup).
80+
- Verify examples render (`pnpm --filter @tabler/docs build`) and links work.

‎.agents/rules/main.mdc‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
description: Tabler Project Rules
3+
globs:
4+
alwaysApply: true
5+
---
6+
7+
8+
# Tabler — project rules
9+
10+
Shared instructions for all AI agents (Claude Code, Cursor, etc.). Canonical agent configuration lives in `.agents/` (`rules/` + `skills/`); `.claude/skills` is a symlink into it.
11+
12+
## Project structure
13+
14+
- `core/` — `@tabler/core`: SCSS sources (`core/scss/`), JS, the distributable framework.
15+
- `preview/` — `@tabler/preview`: demo site built with Astro (pages in `preview/pages/*.astro`).
16+
- `docs/` — `@tabler/docs`: documentation site built with Astro (pages in `docs/pages/**/*.mdx`); docs-specific rules: `.agents/rules/docs.mdc`.
17+
- `shared/astro/` — Astro components, layouts, and lib shared by `preview` and `docs` (imported via the `@shared` alias).
18+
- `shared/data/` — JSON data used by pages (imported via the `@data` alias).
19+
- Package manager: pnpm workspaces + turbo. Node.js >= 22.12.
20+
21+
## Language
22+
23+
- Write all repository content in English: code, comments, documentation, commit messages, PR titles and descriptions.
24+
- Use simple English in documentation: short sentences, common words, direct instructions.
25+
26+
## HTML and component guidelines
27+
28+
### Astro pages and components
29+
30+
- Pages are Astro components; reusable markup lives in `shared/astro/components/`.
31+
- Icons: use the shared component — `<Icon name="home" />` (import from `@shared/components/Icon.astro`).
32+
- Links between preview pages are relative: `./job-listing.html` (root-level pages).
33+
- Boolean HTML attributes in Astro: `selected={true}` renders a bare attribute, but some attributes (e.g. `multiple`) render `="true"` — use `multiple ? '' : undefined` when a bare attribute is required.
34+
35+
### CSS classes
36+
37+
- Use Bootstrap 5 classes plus Tabler's custom classes.
38+
- Follow Tabler's CSS custom properties pattern: `--#{$prefix}component-property`.
39+
- Cards: `card` for containers, `card-body` for content, `card-header` / `card-title` for headers.
40+
- Buttons: `btn` for all buttons; `btn-primary` for primary actions; plain `btn` for secondary actions (do not use `btn-outline-secondary`); `btn-sm` for small buttons; `w-100` for full width.
41+
- Forms: `form-control` for inputs, `form-label` for labels, `form-check` for checkboxes/radios, `form-select` for dropdowns.
42+
- Layout: Bootstrap grid (`row`, `col-*`), `container-xl` for main containers, `page-wrapper` / `page-body` for page structure.
43+
- Badges: plain `badge` class; do not use `badge-outline` or `badge-primary`; do not change badge text color.
44+
- Markdown content: wrap in a `markdown` class container.
45+
46+
### Accessibility
47+
48+
- Use semantic HTML elements and proper heading hierarchy.
49+
- Include ARIA labels (e.g. `aria-label` for icon-only buttons) and alt text for images.
50+
51+
## SCSS guidelines
52+
53+
- Use semantic class names that describe purpose, not appearance.
54+
- Keep Bootstrap-compatible class naming conventions.
55+
- Group related styles together with clear comments; keep consistent spacing and indentation.
56+
57+
## Git conventions
58+
59+
### Branch naming
60+
61+
- Lowercase, kebab-case, format: `<type>/<short-description>` or `<type>/<issue-id>-<short-description>` (issue id as `gh-123`, never `#`).
62+
- Allowed types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `build`, `ci`, `perf`, `style`, `revert`.
63+
- Examples: `feat/gh-123-add-stepper-component`, `fix/markdown-table-overflow`.
64+
- Branch off `dev` by default.
65+
66+
### Commit messages
67+
68+
- English, conventional commit format when possible: `feat: add progress steps component`, `fix: update icon stroke width for better visibility`.
69+
70+
### Pull requests
71+
72+
- Title in English, capitalized, present tense, ideally <= 72 chars, no trailing period.
73+
- Description in English, skimmable (bullets, short paragraphs), focused on **why** the change is needed and its user-visible effect. Recommended template:
74+
75+
```md
76+
## Summary
77+
- <1-3 bullets describing the change and why>
78+
79+
## Changes
80+
- <key implementation notes, non-obvious decisions>
81+
```
82+
83+
- Mark WIP PRs as drafts.
84+
85+
### Changesets
86+
87+
- Each change gets a separate file in `.changeset/` with a descriptive kebab-case filename (e.g. `progress-sizes.md`).
88+
- One sentence per changeset, starting with an action verb (`Added`, `Updated`, `Fixed`, `Removed`), with backticks for code elements (`.btn-ghost`, `stroke-width`, `1.5`, `arrow-up`).
89+
- Version bumps: **major** = breaking changes; **minor** = new features, components, or pages; **patch** = bug fixes, small improvements, style/accessibility tweaks.
90+
- Packages: `"@tabler/core"` for SCSS/JS/classes, `"@tabler/preview"` for demo pages, `"@tabler/docs"` for documentation; list multiple packages when the change spans areas.
91+
- Example:
92+
93+
```md
94+
---
95+
"@tabler/core": minor
96+
"@tabler/preview": minor
97+
---
98+
99+
Added Progress Steps component for step-by-step navigation indicators.
100+
```
101+
102+
- If a PR changes SCSS or any package behavior, it must include a changeset.

.cursor/skills/generate-changeset/SKILL.md renamed to .agents/skills/generate-changeset/SKILL.md

File renamed without changes.

.cursor/skills/mr-description/SKILL.md renamed to .agents/skills/mr-description/SKILL.md

File renamed without changes.

‎.agents/skills/write-docs/SKILL.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
name: write-docs
3+
description: Write or update Tabler documentation pages in simple English using the current docs schema. Use when the user asks to create docs, edit docs, add new feature docs to an existing page, or standardize docs structure across any docs category.
4+
disable-model-invocation: true
5+
---
6+
7+
# Write Tabler Docs
8+
9+
Write docs directly in files (do not stop at draft mode) and follow the current Tabler documentation schema.
10+
11+
## 1. Scope and behavior
12+
13+
- Works for any docs page type under `docs/pages/**` (components, utilities, forms, layout, plugins, base, getting started, emails, illustrations, icons, index pages). Pages are MDX: leaf pages `foo.mdx`, parents with sub-pages `foo/index.mdx`.
14+
- Edit existing pages when the user asks to document new functionality in an existing component/page.
15+
- Create new pages when needed.
16+
- Use simple English in all prose.
17+
18+
## 2. Required language style (simple English)
19+
20+
- Use short sentences and common words.
21+
- Keep one main idea per sentence when possible.
22+
- Prefer direct verbs: `Use`, `Add`, `Set`, `Show`.
23+
- Avoid buzzwords and marketing filler.
24+
- Keep paragraphs short and easy to scan.
25+
26+
## 3. Frontmatter rules
27+
28+
Default frontmatter (required unless user asks otherwise):
29+
30+
```yaml
31+
---
32+
title: ...
33+
summary: ...
34+
description: ...
35+
layout: '@shared/layouts/DocsMdxLayout.astro'
36+
---
37+
```
38+
39+
Rules:
40+
41+
- Keep frontmatter static YAML only.
42+
- By default, include only `title`, `summary`, `description`, and `layout`.
43+
- Add extended keys (for example `bootstrapLink`, `order`, `plugin`, `docs-libs`, `redirect`) only when the user explicitly asks for them or nearby pages in the same category use them.
44+
45+
## 4. Documentation schema to follow
46+
47+
Use this section order as the default structure:
48+
49+
1. `## Overview`
50+
2. `## Installation` (optional)
51+
3. `## Variants` or `## Usage` (choose one based on page type)
52+
4. `## Examples` (optional)
53+
5. `## Accessibility`
54+
6. `## SCSS variables` (optional)
55+
7. `## Migration notes` (optional)
56+
57+
Guidance by page type:
58+
59+
- Component-like pages: prefer `Variants`.
60+
- Utility or workflow pages: prefer `Usage`.
61+
- Library/package pages (for example icons, emails): keep `Installation` + `Usage`.
62+
- Intro/index pages: may use concise overview sections, but keep hierarchy clear and consistent.
63+
64+
## 5. Example and snippet pattern
65+
66+
For visual examples, use the shared `Example` component (import after the frontmatter):
67+
68+
```mdx
69+
import Example from '@shared/components/docs/Example.astro';
70+
71+
<Example>
72+
<button class="btn btn-primary">Primary button</button>
73+
</Example>
74+
```
75+
76+
- Add 1-2 short sentences before each preview block to explain what the preview shows.
77+
- Use props when useful: `hideCode`, `centered`, `vertical`, `raw`, `column`, `bg`, `height`, `codeOnly`.
78+
- For a cleaner displayed snippet than the rendered preview, pass `code={...}`.
79+
- For icons and other shared components inside examples, import them from `@shared/components/` (for example `<Icon name="plus" />`).
80+
- Raw HTML in the `Example` slot is reserialized by MDX — keep markup lines attached to tags to avoid stray `<p>` wrapping.
81+
82+
## 6. Workflow for each request
83+
84+
1. Identify target file(s) in `docs/pages/**`.
85+
2. Read the target page and 2-3 nearby pages in the same category to match tone and conventions.
86+
3. Apply the schema from section 4.
87+
4. Write/update the page directly in file(s).
88+
5. Keep only required frontmatter by default.
89+
6. Ensure prose is in simple English.
90+
7. Verify heading hierarchy (`##` then `###`) and snippet validity.
91+
92+
## 7. Rules while updating existing docs
93+
94+
- Preserve valid existing content that is still correct.
95+
- Add new functionality docs as focused new subsection(s), usually under `Variants`, `Usage`, or `Examples`.
96+
- Remove or rewrite only conflicting or outdated text.
97+
- Keep naming and terms consistent across the page.
98+
99+
## 8. Quality checklist before finishing
100+
101+
- [ ] Uses simple English.
102+
- [ ] Frontmatter uses static YAML.
103+
- [ ] Default frontmatter contains only `title`, `summary`, `description`, `layout` (unless user requested extra keys).
104+
- [ ] Follows schema and heading hierarchy.
105+
- [ ] Examples use the `Example` component pattern where applicable.
106+
- [ ] Accessibility section exists for interactive UI docs.
107+
- [ ] No mention of changeset reminders unless user asks.

‎.build/zip-package.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ const zip = new AdmZip()
2222
zip.addLocalFolder(path.join(__dirname, '../preview/dist'), 'dashboard')
2323

2424
zip.addLocalFile(
25-
path.join(__dirname, '../preview/static', 'og.png'),
25+
path.join(__dirname, '../shared/static', 'og.png'),
2626
'.',
2727
'preview.png'
2828
)

‎.changeset/astro-migration.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@tabler/preview": minor
3+
"@tabler/docs": minor
4+
---
5+
6+
Updated the `preview` and `docs` packages to build with Astro instead of Eleventy, keeping the generated pages identical and moving shared components to `shared/astro/`.

0 commit comments

Comments
 (0)