# Tags

Zensical adds first-class support for categorizing pages with tags, which allows users to discover related pages via [search](<https://zensical.org/docs/setup/search/index.md>). If your documentation is large, tags can help users find relevant information faster.

## Configuration

Zensical provides a native implementation of the `tags` plugin, adapted from the configuration and behavior of the Material for MkDocs [tags plugin](<https://squidfunk.github.io/mkdocs-material/plugins/tags/>). Enable it in your configuration:

```toml
[project.plugins.tags]
```

```yaml
plugins:
  - tags
```

The implementation supports the existing plugin configuration, including tag listings and advanced tag settings. Refer to the original [plugin documentation](<https://squidfunk.github.io/mkdocs-material/plugins/tags/>) for all available options and listing syntax, and check the [compatibility entry](<https://zensical.org/docs/compatibility/mkdocs/plugins/#tags>) for Zensical-specific information.

### Tag icons and identifiers

Each tag can be associated with an icon, which is rendered inside the tag. Before assigning icons to tags, associate each tag with a unique identifier by adding the following to your configuration:

```toml
[project.extra.tags]
<tag> = "<identifier>"
```

```yaml
extra:
  tags:
    <tag>: <identifier>
```

The identifier can only include alphanumeric characters, as well as dashes and underscores. For example, if you have a tag `Compatibility`, you can set `compat` as an identifier:

```toml
[project.extra.tags]
Compatibility = "compat"
```

```yaml
extra:
  tags:
    Compatibility: compat
```

Identifiers can be reused between tags to assign groups of tags the same icon. Tags that are not explicitly associated with an identifier will use the default tag icon.

Next, each identifier can be associated with an icon, including a [custom icon](<https://zensical.org/docs/setup/logo-and-icons/#additional-icons>), under the `theme.icon` configuration setting:

```toml
[project.theme.icon.tag]
default = "<icon>"
<identifier> = "<icon>"
```

```yaml
theme:
  icon:
    tag:
      default: <icon>
      <identifier>: <icon>
```

> [!NOTE]
>
> **Expand to see an example**
>
> ```toml
> [project.theme.icon.tag]
> default = "lucide/hash"
> html = "fontawesome/brands/html5"
> js = "fontawesome/brands/js"
> css = "fontawesome/brands/css3"
>
> [project.extra.tags]
> HTML5 = "html"
> JavaScript = "js"
> CSS = "css"
> ```
>
> ```yaml
> theme:
>   icon:
>     tag:
>       default: lucide/hash
>       html: fontawesome/brands/html5
>       js: fontawesome/brands/js
>       css: fontawesome/brands/css3
> extra:
>   tags:
>     HTML5: html
>     JavaScript: js
>     CSS: css
> ```

## Usage

### Add tags

Tags can be added to a document with the front matter `tags` property. They can also be used in search without any further configuration. Add the following lines at the top of a Markdown file:

```yaml
---
tags:
  - HTML5
  - JavaScript
  - CSS
---

# Page title
...
```

The page will now render with those tags at the bottom, and users will be able to filter by them in search.

### Hide tags on a page

While tags are rendered at the bottom of each page, you can hide them for a specific page with the front matter `hide` property:

```yaml
---
hide:
  - tags
---

# Page title
...
```