Add CONTRIBUTING.md, docs markdown linting and fixed dev server ports (#2714)

2026-08-05 01:44:41 +04:00 · 2026-07-29 00:04:08 +02:00
parent 8f86f1f4a7
commit 1ec82d0038
58 changed files with 284 additions and 170 deletions
@@ -11,7 +11,7 @@ To be able to use the autosize in your application you will need to install the

 ## Default markup

-Add the autosize element to your input to make it automatically adjust to the length of a text as a user types it. 
+Add the autosize element to your input to make it automatically adjust to the length of a text as a user types it.

 To create autosize textarea, add the `data-bs-toggle="autosize"` attribute to the textarea element:

@@ -100,6 +100,6 @@ Use `.badge-sm` or `.badge-lg` to change badge size according to your needs. The
 </Example>


-## More examples 
+## More examples

 If you want to see more examples of badges, you can check out the [Bootstrap documentation](https://getbootstrap.com/docs/5.3/components/badge/) for badges. You can also find more examples in the Tabler [Badges](https://preview.tabler.io/badges.html) preview.
@@ -65,7 +65,7 @@ Here is a list of classes:
 {gradients.map((gradient, i) => { return ( <li class={`card-gradient-${gradient}`}>{gradient.charAt(0).toUpperCase() + gradient.slice(1)}</li> ) })}
 </ul>
 <Example>
-	
+
 {gradients.map((gradient, i) => {
 	return (
 		<div class={`card card-gradient card-gradient-${gradient}`}>
@@ -12,7 +12,7 @@ import Example from '@shared/components/docs/Example.astro';

 You can adjust the datagrid to your needs by setting the values of variables:

-| Variable | Description | Default |
-|----------|-------------|---------|
-| `--tblr-datagrid-item-width` | Width of the datagrid item | `15rem` |
-| `--tblr-datagrid-padding` | Gap between the datagrid items | `1.5rem` |
+| Variable                     | Description                    | Default  |
+|------------------------------|--------------------------------|----------|
+| `--tblr-datagrid-item-width` | Width of the datagrid item     | `15rem`  |
+| `--tblr-datagrid-padding`    | Gap between the datagrid items | `1.5rem` |
@@ -24,7 +24,7 @@ When you have a lot of pages, you can use first and last links to quickly naviga

 ## Offset

-If the count of pages is too large, you can use offset to show only a few pages at a time. 
+If the count of pages is too large, you can use offset to show only a few pages at a time.

 <Example centered vertical>
 <Pagination offset={3} count={20} />
@@ -33,7 +33,7 @@ The example below shows the default progress step structure.
 Use color classes to mark completed steps. Set `aria-current="step"` on the current item.

 <Example>
-<ProgressSteps count={4} active={2} ariaLabel="Setup progress" /> 
+<ProgressSteps count={4} active={2} ariaLabel="Setup progress" />
 </Example>

 ### Custom labels
@@ -41,7 +41,7 @@ Use color classes to mark completed steps. Set `aria-current="step"` on the curr
 Use hidden labels so assistive technologies can announce meaningful step names.

 <Example>
-<ProgressSteps labels="Account,Profile,Billing,Review" active={3} ariaLabel="Checkout progress" /> 
+<ProgressSteps labels="Account,Profile,Billing,Review" active={3} ariaLabel="Checkout progress" />
 </Example>

 ### Color state
@@ -57,5 +57,5 @@ Use contextual background classes on completed and current items. This helps mat
 Use utility classes on `.progress-steps` to control width and placement in layouts.

 <Example>
-<ProgressSteps count={5} active={1} class="w-50" id="profile-progress" ariaLabel="Profile completion" /> 
+<ProgressSteps count={5} active={1} class="w-50" id="profile-progress" ariaLabel="Profile completion" />
 </Example>
@@ -51,7 +51,7 @@ You can create a progress bar which shows indeterminate progress by adding `.pro
 You can also use the native HTML5 `<progress>` element. It is a great way to create a progress bar without the need for additional HTML elements. This is what it looks like:

 <Example>
-<progress class="progress progress-sm" value="15" max="100" /> 
+<progress class="progress progress-sm" value="15" max="100" />
 </Example>

 ## Progress color
@@ -112,7 +112,7 @@ page, the progress bar could gradually fill up, creating a sense of momentum and
 Thanks to this you can create a nice looking statistics section:

 <Example columnFullWidth>
-<ProgressBg value="65" text="Poland" showValue true /> <ProgressBg value="35" text="Germany" showValue true /> <ProgressBg value="28" text="United States" showValue true /> <ProgressBg value="20" text="United Kingdom" showValue true /> <ProgressBg value="15" text="France" showValue true /> 
+<ProgressBg value="65" text="Poland" showValue true /> <ProgressBg value="35" text="Germany" showValue true /> <ProgressBg value="28" text="United States" showValue true /> <ProgressBg value="20" text="United Kingdom" showValue true /> <ProgressBg value="15" text="France" showValue true />
 </Example>

 ## Progress background colors
@@ -120,5 +120,5 @@ Thanks to this you can create a nice looking statistics section:
 You can combine progress background with contextual light colors to better separate categories.

 <Example columnFullWidth>
-<ProgressBg value="75" text="Success" color="success-lt" showValue true /> <ProgressBg value="60" text="Warning" color="warning-lt" showValue true /> <ProgressBg value="40" text="Danger" color="danger-lt" showValue true /> <ProgressBg value="90" text="Info" color="info-lt" showValue true /> 
+<ProgressBg value="75" text="Success" color="success-lt" showValue true /> <ProgressBg value="60" text="Warning" color="warning-lt" showValue true /> <ProgressBg value="40" text="Danger" color="danger-lt" showValue true /> <ProgressBg value="90" text="Info" color="info-lt" showValue true />
 </Example>
@@ -57,7 +57,7 @@ The results can be seen in the example below.
 <nav class="nav nav-segmented nav-segmented-vertical" role="tablist"> <button class="nav-link active" role="tab" data-bs-toggle="tab" aria-selected="true" aria-current="page" > <Icon name="list" /> List </button> <button class="nav-link" role="tab" data-bs-toggle="tab" aria-selected="false" tabindex="-1"> <Icon name="layout" /> Kanban </button> <button class="nav-link" role="tab" data-bs-toggle="tab" aria-selected="false" tabindex="-1"> <Icon name="calendar" /> Calendar </button> <button class="nav-link" role="tab" data-bs-toggle="tab" aria-selected="false" tabindex="-1"> <Icon name="files" /> Files </button> </nav>
 </Example>

-## Sizes 
+## Sizes

 You can also change the size of the segmented control. To do this, add the `nav-sm` or `nv-lg` class to the `nav` element. The `nav-sm` class will make the segmented control smaller, while the `nav-lg` class will make it larger.

@@ -53,7 +53,7 @@ The dots can also be animated. To do this, add the `.status-dot-animated` class.
 <span class="status-dot status-dot-animated status-blue"></span>
 ```

-The animated status dots can be used in the same way as the regular status dots. 
+The animated status dots can be used in the same way as the regular status dots.

 <Example>
 <span class="status-dot status-dot-animated status-blue"></span> <span class="status-dot status-dot-animated status-azure"></span> <span class="status-dot status-dot-animated status-indigo"></span> <span class="status-dot status-dot-animated status-purple"></span> <span class="status-dot status-dot-animated status-pink"></span> <span class="status-dot status-dot-animated status-red"></span> <span class="status-dot status-dot-animated status-orange"></span> <span class="status-dot status-dot-animated status-yellow"></span> <span class="status-dot status-dot-animated status-lime"></span> <span class="status-dot status-dot-animated status-green"></span> <span class="status-dot status-dot-animated status-teal"></span> <span class="status-dot status-dot-animated status-cyan"></span>
@@ -11,7 +11,7 @@ import Example from '@shared/components/docs/Example.astro';

 Steps provide a clear visual representation of a user’s progress through a multi-step process. By showing what has been completed and what remains, steps enhance usability and encourage task completion.

-To create a default progress tracker, use the `.steps` class and define each step as a `.step-item`. The active step clearly indicates the current position in the process. 
+To create a default progress tracker, use the `.steps` class and define each step as a `.step-item`. The active step clearly indicates the current position in the process.

 ```html
 <div class="steps">
@@ -75,7 +75,7 @@ For designs with limited space, use progress indicators without titles and add t

 ## Steps with numbers

-Use the `steps-counter` class to create a progress tracker with numbers instead of titles and change the color to customize it. 
+Use the `steps-counter` class to create a progress tracker with numbers instead of titles and change the color to customize it.

 ```html
 <div class="steps steps-counter">...</div>
@@ -14,7 +14,7 @@ import Payment from '@shared/components/ui/Payment.astro';
 Use `.tag` for one inline tag item. The base style supports text and an optional `.btn-close` remove action.

 <Example centered>
-<span class="tag"> Label <a href="#" class="btn-close" aria-label="Remove label"></a> </span> 
+<span class="tag"> Label <a href="#" class="btn-close" aria-label="Remove label"></a> </span>
 </Example>

 ## Variants
@@ -24,7 +24,7 @@ Use `.tag` for one inline tag item. The base style supports text and an optional
 Use `.tag-icon` for a leading icon inside a tag. The icon uses compact size and secondary text color.

 <Example centered>
-<span class="tag"> <Icon name="star" class="tag-icon" /> Featured <a href="#" class="btn-close" aria-label="Remove featured tag"></a> </span> 
+<span class="tag"> <Icon name="star" class="tag-icon" /> Featured <a href="#" class="btn-close" aria-label="Remove featured tag"></a> </span>
 </Example>

 ### With avatar, flag, or payment
@@ -40,7 +40,7 @@ Use `.tag-avatar`, `.tag-flag`, or `.tag-payment` to add media at the start of t
 Use `.tag-badge` for small numeric or status counters. The badge variant keeps compact padding for tag layout.

 <Example centered>
-<span class="tag"> Notifications <span class="badge tag-badge">12</span> <a href="#" class="btn-close" aria-label="Remove notifications tag"></a> </span> 
+<span class="tag"> Notifications <span class="badge tag-badge">12</span> <a href="#" class="btn-close" aria-label="Remove notifications tag"></a> </span>
 </Example>

 ### With checkbox
@@ -48,7 +48,7 @@ Use `.tag-badge` for small numeric or status counters. The badge variant keeps c
 Use `.tag-check` on a checkbox when the tag should be selectable. This variant is useful for filter sets and selectable labels.

 <Example centered>
-<span class="tag"> <input type="checkbox" class="form-check-input tag-check" checked /> Selected <a href="#" class="btn-close" aria-label="Remove selected tag"></a> </span> 
+<span class="tag"> <input type="checkbox" class="form-check-input tag-check" checked /> Selected <a href="#" class="btn-close" aria-label="Remove selected tag"></a> </span>
 </Example>

 ## Examples
@@ -27,7 +27,7 @@ Look at the examples below to see how the image check works:

 ## Radio buttons

-If you want to use the image check as a radio button, you can change the input type to `radio`. 
+If you want to use the image check as a radio button, you can change the input type to `radio`.

 <Example>
 <div class="mb-3"> <label class="form-label">Image Check Radio</label> <div class="row g-2"> <div class="col-3"> <label class="form-imagecheck mb-2"> <input name="image" type="radio" value="1" class="form-imagecheck-input" /> <span class="form-imagecheck-figure"> <img src="/static/photos/woman-drinking-hot-tea-in-her-home-office.jpg" alt="" class="form-imagecheck-image" /> </span> </label> </div> <div class="col-3"> <label class="form-imagecheck mb-2"> <input name="image" type="radio" value="2" class="form-imagecheck-input" checked /> <span class="form-imagecheck-figure"> <img src="/static/photos/young-woman-sitting-on-the-sofa-and-working-on-her-laptop-3.jpg" alt="" class="form-imagecheck-image" /> </span> </label> </div> <div class="col-3"> <label class="form-imagecheck mb-2"> <input name="image" type="radio" value="3" class="form-imagecheck-input" /> <span class="form-imagecheck-figure"> <img src="/static/photos/beautiful-blonde-woman-relaxing-with-a-can-of-coke-on-a-tree-stump-by-the-beach.jpg" alt="" class="form-imagecheck-image" /> </span> </label> </div> <div class="col-3"> <label class="form-imagecheck mb-2"> <input name="image" type="radio" value="4" class="form-imagecheck-input" checked /> <span class="form-imagecheck-figure"> <img src="/static/photos/book-on-the-grass.jpg" alt="" class="form-imagecheck-image" /> </span> </label> </div> </div> </div>
@@ -44,7 +44,7 @@ To set up Tabler for development, follow these steps:

 ### Ensure Node.js and pnpm are installed

-You’ll need Node.js (v20 or higher) and pnpm to compile Tabler’s files. If you don’t have them installed, download and install them from the official websites:
+You’ll need Node.js (v22.12 or higher) and pnpm to compile Tabler’s files. If you don’t have them installed, download and install them from the official websites:

 - [Node.js](https://nodejs.org/)
 - [pnpm](https://pnpm.io/) (we use pnpm over other package managers for faster installation).
@@ -70,6 +70,32 @@ pnpm run dev
 Make your changes in the appropriate folders, such as `./core/`, `./preview/` or `./docs/`. Avoid modifying files in any `dist` folders, as they are auto-generated during the build process and will be overwritten.
 </div>

+## Project structure
+
+Tabler is a pnpm monorepo. The packages you will work with most often are:
+
+- `core/` - the framework itself: SCSS sources in `core/scss/` and JavaScript in `core/js/`. This is where CSS classes and components are defined.
+- `preview/` - the demo website built with [Astro](https://astro.build). Pages live in `preview/pages/*.astro`.
+- `docs/` - the documentation website, also built with Astro. Pages live in `docs/pages/**/*.mdx`.
+- `shared/astro/` - Astro components, layouts and helpers shared by the preview and docs websites. Import them with the `@shared` alias, for example `import Button from '@shared/components/Button.astro'`.
+- `shared/data/` - JSON data used by demo pages. Import it with the `@data` alias.
+
+A few practical rules:
+
+- If you add a new CSS class or component style, change it in `core/scss/` and show it on a preview page.
+- If you add or change a reusable piece of markup, put it in `shared/astro/components/`, not in a single page.
+- If you add a new feature, document it in `docs/pages/`.
+
+## Add a changeset
+
+If your change affects any package (new feature, bug fix, new page), add a changeset - a short note used to build the changelog:
+
+```bash
+pnpm exec changeset
+```
+
+Select the affected packages (`@tabler/core`, `@tabler/preview` or `@tabler/docs`), pick the bump type (`patch` for fixes, `minor` for new features) and write a one-sentence description, for example: `Added .btn-ghost variant for buttons.`
+
 ## Compiling for Production

 Before submitting a pull request, ensure your changes are properly compiled and tested:
@@ -14,4 +14,4 @@ Tabler is fully responsive and compatible with all modern browsers. Thanks to it

 Tabler is a perfect solution if you want to create an interface which is not only user-friendly but also fully responsive. Thanks to the big choice of ready-made components, you can customize your design and adapt it to the needs of even the most demanding users. On top of that, Tabler is an open source solution, continuously developed and improved by the open source community.

-<img src="https://raw.githubusercontent.com/tabler/tabler/dev/shared/static/tabler-preview.png?2" src-dark="https://raw.githubusercontent.com/tabler/tabler/dev/shared/static/tabler-preview-dark.png?2" alt="Screencap of tabler site showing global traffic and statistics" />
+<img src="https://raw.githubusercontent.com/tabler/tabler/dev/shared/static/tabler-preview.png?2" src-dark="https://raw.githubusercontent.com/tabler/tabler/dev/shared/static/tabler-preview-dark.png?2" alt="Screencap of tabler site showing global traffic and statistics" />
@@ -9,6 +9,8 @@ import Example from '@shared/components/docs/Example.astro';

 This guide will take you through the essential steps to set up Tabler in your project, from creating a basic HTML file to incorporating Tabler’s styles and scripts. Let’s dive in!

+## Setup
+
 <div class="steps steps-vertical">

 ### Create a Basic HTML File
@@ -11,6 +11,7 @@ Tabler is an open-source project licensed under the **MIT license**, giving you
 ## What You Can Do with Tabler

 The MIT license allows you to:
+
 - Use Tabler in **commercial projects**.
 - Use Tabler in **personal or private projects**.
 - **Modify and customize** the source code to fit your requirements.
@@ -24,6 +25,7 @@ The MIT license allows you to:
 ## What You Must Do When Using Tabler

 When using Tabler, you must:
+
 1. Include the **license notice** in all copies of the work.
 2. Include the **copyright notice** in all copies of the work, except for the footer of the example HTML pages provided in the repository.

@@ -13,7 +13,7 @@ Navigation bars are essential components of modern web applications, providing u
 If you want to create a horizontal navigation bar, you can use the `.nav` class. The `.nav-item` class is used to style each item within the navigation bar, and `.nav-link` is applied to the links. The `.active` class highlights the current active link, while the `.disabled` class styles non-clickable links.

 Look at the example below to see how the horizontal navigation bar is displayed.
- 
+
 <Example>
 <ul class="nav"> <li class="nav-item"> <a class="nav-link active" aria-current="page" href="#">Active</a> </li> <li class="nav-item"> <a class="nav-link" href="#">Link</a> </li> <li class="nav-item"> <a class="nav-link disabled" aria-disabled="true">Disabled</a> </li> </ul>
 </Example>
@@ -120,11 +120,9 @@ Use gradient utilities on card sections to highlight key content areas.
      <h3 class="card-title mb-1">Performance</h3>
      <p class="text-secondary mb-0">Weekly trend overview</p>
    </div>
-
    <div class="card-body">
      <p class="mb-0">Card content</p>
    </div>
-
  </div>
 </Example>

@@ -9,7 +9,7 @@ import Example from '@shared/components/docs/Example.astro';
 Margin utilities allow you to control the space between elements, providing flexibility to suit different design needs. These utilities are especially useful for creating spacing between components or aligning them consistently. Below are examples of how to use margin utilities for various directions and sizes.


-### Margin size
+## Margin size

 In the table below you can see the available margin sizes.

@@ -26,7 +26,7 @@ Name|Value
 8|8rem


-### Margin
+## Margin

 Use the `.m-*` utilities to control the margin of an element. Margin utilities are used to create consistent spacing around an element, ensuring that the layout is visually balanced.

@@ -34,7 +34,7 @@ Use the `.m-*` utilities to control the margin of an element. Margin utilities a
 <div class="d-flex"> <div class="bg-purple-lt"> <div class="px-3 py-2 m-0 bg-purple rounded text-white font-monospace">.m-0</div> </div> </div> <div class="d-flex"> <div class="bg-purple-lt"> <div class="px-3 py-2 m-4 bg-purple rounded text-white font-monospace">.m-4</div> </div> </div> <div class="d-flex"> <div class="bg-purple-lt"> <div class="px-3 py-2 m-8 bg-purple rounded text-white font-monospace">.m-8</div> </div> </div>
 </Example>

-### Start margin
+## Start margin

 Start margins control the spacing to the left of an element, helping to create consistent horizontal gaps between elements. Start margin class names are prefixed with `ms-`.

@@ -46,7 +46,7 @@ Start margins control the spacing to the left of an element, helping to create c
 <div class="d-flex"> <div class="bg-red-lt"> <div class="px-3 py-2 ms-0 bg-red rounded text-white font-monospace">.ms-0</div> </div> </div> <div class="d-flex"> <div class="bg-red-lt"> <div class="px-3 py-2 ms-4 bg-red rounded text-white font-monospace">.ms-4</div> </div> </div> <div class="d-flex"> <div class="bg-red-lt"> <div class="px-3 py-2 ms-8 bg-red rounded text-white font-monospace">.ms-8</div> </div> </div>
 </Example>

-### End margin
+## End margin

 End margins control the spacing on the right side of an element. These utilities are helpful for creating visual separation between elements that flow horizontally. End margin class names are prefixed with `me-`.

@@ -58,7 +58,7 @@ End margins control the spacing on the right side of an element. These utilities
 <div class="d-flex"> <div class="bg-orange-lt"> <div class="px-3 py-2 ms-0 bg-orange rounded text-white font-monospace">.me-0</div> </div> </div> <div class="d-flex"> <div class="bg-orange-lt"> <div class="px-3 py-2 me-4 bg-orange rounded text-white font-monospace">.me-4</div> </div> </div> <div class="d-flex"> <div class="bg-orange-lt"> <div class="px-3 py-2 me-8 bg-orange rounded text-white font-monospace">.me-8</div> </div> </div>
 </Example>

-### Top margin
+## Top margin

 Top margins define the spacing above an element. This is useful for separating stacked components or creating vertical spacing between sections. Top margin class names are prefixed with `mt-`.

@@ -70,7 +70,7 @@ Top margins define the spacing above an element. This is useful for separating s
 <div class="d-flex"> <div class="bg-yellow-lt"> <div class="px-3 py-2 mt-0 bg-yellow rounded text-white font-monospace">.mt-0</div> </div> </div> <div class="d-flex"> <div class="bg-yellow-lt"> <div class="px-3 py-2 mt-4 bg-yellow rounded text-white font-monospace">.mt-4</div> </div> </div> <div class="d-flex"> <div class="bg-yellow-lt"> <div class="px-3 py-2 mt-8 bg-yellow rounded text-white font-monospace">.mt-8</div> </div> </div>
 </Example>

-### Bottom margin
+## Bottom margin

 Bottom margins control the spacing below an element, helping to create consistent vertical gaps between stacked elements. Bottom margin class names are prefixed with `mb-`.

@@ -82,7 +82,7 @@ Bottom margins control the spacing below an element, helping to create consisten
 <div class="d-flex"> <div class="bg-lime-lt"> <div class="px-3 py-2 mb-0 bg-lime rounded text-white font-monospace">.mb-0</div> </div> </div> <div class="d-flex"> <div class="bg-lime-lt"> <div class="px-3 py-2 mb-4 bg-lime rounded text-white font-monospace">.mb-4</div> </div> </div> <div class="d-flex"> <div class="bg-lime-lt"> <div class="px-3 py-2 mb-8 bg-lime rounded text-white font-monospace">.mb-8</div> </div> </div>
 </Example>

-### Horizontal margin
+## Horizontal margin

 Use the `mx-*` utilities to control the horizontal margin of an element. Horizontal margin utilities are used to create consistent spacing between elements that flow horizontally.

@@ -95,7 +95,7 @@ Use the `mx-*` utilities to control the horizontal margin of an element. Horizon
 </Example>


-### Vertical margin
+## Vertical margin

 Use the `my-*` utilities to control the vertical margin of an element. Vertical margin utilities are used to create consistent spacing between elements that flow vertically.

@@ -127,7 +127,7 @@ Use the `.gap-*` utilities to control the space between elements in a grid layou
 <div class="d-grid gap-6">...</div>
 ```

-```html example 
+```html example
 <div class="d-grid gap-6 bg-indigo-lt">
  <div class="px-3 py-2 bg-indigo text-white rounded">Grid item 1</div>
  <div class="px-3 py-2 bg-indigo text-white rounded">Grid item 2</div>