calvin.erfmann/TagStudio
1
0
Fork 0
mirror of https://github.com/TagStudioDev/TagStudio.git synced 2026-05-21 08:15:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(docs): uniform formatting pass (#1363)

Browse Source 
* refactor(docs): uniform formatting pass

* refactor: ignore formatting of specific files

* fix: add REUSE info to .prettierignore
This commit is contained in:
Travis Abendshien
2026-05-12 09:24:04 -04:00
committed by GitHub
parent eb97476dac
commit e134cb1ecb
34 changed files with 1088 additions and 1077 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1165
docs/changelog.md
View File

File diff suppressed because it is too large Load Diff

1
docs/colors.md
View File

@@ -1,6 +1,7 @@
---
icon: material/palette
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->

97
docs/contributing.md
View File

@@ -1,6 +1,7 @@
---
icon: material/file-plus
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->
@@ -10,11 +11,11 @@ Thank you so much for showing interest in contributing to TagStudio! Here are a
## Getting Started
- Check the [Feature Roadmap](roadmap.md) page to see what priority features there are, the [FAQ](https://github.com/TagStudioDev/TagStudio/blob/main/README.md#faq), as well as the project's [Issues](https://github.com/TagStudioDev/TagStudio/issues) and [Pull Requests](https://github.com/TagStudioDev/TagStudio/pulls).
- If you'd like to add a feature that isn't on the feature roadmap or doesn't have an open issue, **PLEASE create a feature request** issue for it discussing your intentions so any feedback or important information can be given by the team first.
- We don't want you wasting time developing a feature or making a change that can't/won't be added for any reason ranging from pre-existing refactors to design philosophy differences.
- **Please don't** create pull requests that consist of large refactors, _especially_ without discussing them with us first. These end up doing more harm than good for the project by continuously delaying progress and disrupting everyone else's work.
- If you wish to discuss TagStudio further, feel free to join the [Discord Server](https://discord.com/invite/hRNnVKhF2G)!
- Check the [Feature Roadmap](roadmap.md) page to see what priority features there are, the [FAQ](https://github.com/TagStudioDev/TagStudio/blob/main/README.md#faq), as well as the project's [Issues](https://github.com/TagStudioDev/TagStudio/issues) and [Pull Requests](https://github.com/TagStudioDev/TagStudio/pulls).
- If you'd like to add a feature that isn't on the feature roadmap or doesn't have an open issue, **PLEASE create a feature request** issue for it discussing your intentions so any feedback or important information can be given by the team first.
- We don't want you wasting time developing a feature or making a change that can't/won't be added for any reason ranging from pre-existing refactors to design philosophy differences.
- **Please don't** create pull requests that consist of large refactors, _especially_ without discussing them with us first. These end up doing more harm than good for the project by continuously delaying progress and disrupting everyone else's work.
- If you wish to discuss TagStudio further, feel free to join the [Discord Server](https://discord.com/invite/hRNnVKhF2G)!
<!-- prettier-ignore -->
!!! note
@@ -22,20 +23,20 @@ Thank you so much for showing interest in contributing to TagStudio! Here are a
### Contribution Checklist
- I've read the [Feature Roadmap](roadmap.md) page
- I've read the [FAQ](https://github.com/TagStudioDev/TagStudio/blob/main/README.md#faq)
- I've checked the project's [Issues](https://github.com/TagStudioDev/TagStudio/issues) and [Pull Requests](https://github.com/TagStudioDev/TagStudio/pulls)
- **I've created a new issue for my feature/fix _before_ starting work on it**, or have at least notified others in the relevant existing issue(s) of my intention to work on it
- I've set up my development environment including Ruff, Mypy, and PyTest
- I've read the CONTRIBUTING.md/Contributing page on the documentation site as well as the and/or [Style Guide](style.md)
- **_I mean it, I've found or created an issue for my feature/fix!_**
- I've read the [Feature Roadmap](roadmap.md) page
- I've read the [FAQ](https://github.com/TagStudioDev/TagStudio/blob/main/README.md#faq)
- I've checked the project's [Issues](https://github.com/TagStudioDev/TagStudio/issues) and [Pull Requests](https://github.com/TagStudioDev/TagStudio/pulls)
- **I've created a new issue for my feature/fix _before_ starting work on it**, or have at least notified others in the relevant existing issue(s) of my intention to work on it
- I've set up my development environment including Ruff, Mypy, and PyTest
- I've read the CONTRIBUTING.md/Contributing page on the documentation site as well as the and/or [Style Guide](style.md)
- **_I mean it, I've found or created an issue for my feature/fix!_**
<!-- prettier-ignore -->
!!! failure "Unacceptable Code"
The following types of code will NOT be accepted to the project:
- Code that is not yours or does not have a compatible license with TagStudio's [own one](../LICENSE)
- Code that you do not understand and/or cannot explain
- Code that is not yours or does not have a compatible license with TagStudio's [own one](../LICENSE)
- Code that you do not understand and/or cannot explain
## Creating a Development Environment
@@ -80,9 +81,9 @@ A Python linter and code formatter. Ruff uses the `pyproject.toml` as its config
Inside the root repository directory:
- Lint code with `ruff check`
- Some linting suggestions can be automatically formatted with `ruff check --fix`
- Format code with `ruff format`
- Lint code with `ruff check`
- Some linting suggestions can be automatically formatted with `ruff check --fix`
- Format code with `ruff format`
Ruff should automatically discover the configuration options inside the [pyproject.toml](https://github.com/TagStudioDev/TagStudio/blob/main/pyproject.toml) file. For more information, see the [ruff configuration discovery docs](https://docs.astral.sh/ruff/configuration/#config-file-discovery).
@@ -94,16 +95,16 @@ Mypy is a static type checker for Python. It sure has a lot to say sometimes, bu
#### Running Locally
- **(First time only)** Run the following:
- `mkdir -p .mypy_cache`
- `mypy --install-types --non-interactive`
- You can now check code by running `mypy --config-file pyproject.toml .` in the repository root. _(Don't forget the "." at the end!)_
- **(First time only)** Run the following:
- `mkdir -p .mypy_cache`
- `mypy --install-types --non-interactive`
- You can now check code by running `mypy --config-file pyproject.toml .` in the repository root. _(Don't forget the "." at the end!)_
Mypy is also available as a VS Code [extension](https://marketplace.visualstudio.com/items?itemName=matangover.mypy), PyCharm [plugin](https://plugins.jetbrains.com/plugin/11086-mypy), and [more](https://plugins.jetbrains.com/plugin/11086-mypy).
### PyTest
- Run all tests by running `pytest tests/` in the repository root.
- Run all tests by running `pytest tests/` in the repository root.
## Code Style
@@ -111,22 +112,22 @@ See the [Style Guide](style.md)
### Modules & Implementations
- **Do not** modify legacy library code in the `src/core/library/json/` directory
- Avoid direct calls to `os`
- Use `Pathlib` library instead of `os.path`
- Use `platform.system()` instead of `os.name` and `sys.platform`
- Don't prepend local imports with `tagstudio`, stick to `src`
- Use the `logger` system instead of `print` statements
- Avoid nested f-strings
- Use HTML-like tags inside Qt widgets over stylesheets where possible
- **Do not** modify legacy library code in the `src/core/library/json/` directory
- Avoid direct calls to `os`
- Use `Pathlib` library instead of `os.path`
- Use `platform.system()` instead of `os.name` and `sys.platform`
- Don't prepend local imports with `tagstudio`, stick to `src`
- Use the `logger` system instead of `print` statements
- Avoid nested f-strings
- Use HTML-like tags inside Qt widgets over stylesheets where possible
### Commit and Pull Request Style
- Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0) as a guideline for commit messages. This allows us to easily generate changelogs for releases.
- See some [examples](https://www.conventionalcommits.org/en/v1.0.0/#examples) of what this looks like in practice.
- Use clear and concise commit messages. If your commit does too much, either consider breaking it up into smaller commits or providing extra detail in the commit description.
- Pull requests should have an adequate title and description which clearly outline your intentions and changes/additions. Feel free to provide screenshots, GIFs, or videos, especially for UI changes.
- Pull requests should ideally be limited to **a single** feature or fix.
- Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0) as a guideline for commit messages. This allows us to easily generate changelogs for releases.
- See some [examples](https://www.conventionalcommits.org/en/v1.0.0/#examples) of what this looks like in practice.
- Use clear and concise commit messages. If your commit does too much, either consider breaking it up into smaller commits or providing extra detail in the commit description.
- Pull requests should have an adequate title and description which clearly outline your intentions and changes/additions. Feel free to provide screenshots, GIFs, or videos, especially for UI changes.
- Pull requests should ideally be limited to **a single** feature or fix.
<!-- prettier-ignore -->
!!! important
@@ -138,24 +139,24 @@ See the [Style Guide](style.md)
### Runtime Requirements
- Final code must function on supported versions of Windows, macOS, and Linux:
- Windows: 10, 11
- macOS: 13.0+
- Linux: _Varies_
- Final code must **_NOT:_**
- Contain superfluous or unnecessary logging statements
- Cause unreasonable slowdowns to the program outside of a progress-indicated task
- Cause undesirable visual glitches or artifacts on screen
- Final code must function on supported versions of Windows, macOS, and Linux:
- Windows: 10, 11
- macOS: 13.0+
- Linux: _Varies_
- Final code must **_NOT:_**
- Contain superfluous or unnecessary logging statements
- Cause unreasonable slowdowns to the program outside of a progress-indicated task
- Cause undesirable visual glitches or artifacts on screen
## Documentation Guidelines
Documentation contributions include anything inside of the `docs/` folder, as well as the `README.md` and `CONTRIBUTING.md` files. Documentation inside the `docs/` folder is built and hosted on our static documentation site, [docs.tagstud.io](https://docs.tagstud.io/).
- Use "[dash-case / kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case)" for file and folder names
- Follow the folder structure pattern
- Don't add images or other media with excessively large file sizes
- Provide alt text for all embedded media
- Use "[Title Case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case)" for title capitalization
- Use "[dash-case / kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case)" for file and folder names
- Follow the folder structure pattern
- Don't add images or other media with excessively large file sizes
- Provide alt text for all embedded media
- Use "[Title Case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case)" for title capitalization
## Translation Guidelines

8
docs/developing.md
View File

@@ -1,6 +1,7 @@
---
icon: material/code-braces
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->
@@ -87,10 +88,9 @@ If you choose to manually set up a virtual environment and install dependencies
```
2. Activate your environment:
- Windows w/Powershell: `.venv\Scripts\Activate.ps1`
- Windows w/Command Prompt: `.venv\Scripts\activate.bat`
- Linux/macOS: `source .venv/bin/activate`
- Windows w/Powershell: `.venv\Scripts\Activate.ps1`
- Windows w/Command Prompt: `.venv\Scripts\activate.bat`
- Linux/macOS: `source .venv/bin/activate`
<!-- prettier-ignore -->
!!! info "Supported Shells"

55
docs/entries.md
View File

@@ -1,6 +1,7 @@
---
icon: material/file
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->
@@ -24,33 +25,33 @@ To fix file entries that have become unlinked, select the "Fix Unlinked Entries"
## Internal Structure
- `id` (`INTEGER`/`int`, `UNIQUE`, `NOT NULL`, `PRIMARY KEY`)
- The ID for the file entry.
- Used for guaranteed unique references.
- `folder` (`INTEGER`/`int`, `NOT NULL`, `FOREIGN KEY`)
- _Not currently used, may be removed._
- `path` (`VARCHAR`/`Path`, `UNIQUE`, `NOT NULL`)
- The filename and filepath relative to the root of the library folder.
- (E.g. for library "Folder", path = "any_subfolders/filename.txt")
- `suffix` (`VARCHAR`/`str`, `NOT NULL`)
- The filename suffix with no leading dot.
- Used for quicker file extension checks.
- `date_created` (`DATETIME`/`Datetime`)
- _Not currently used, will be implemented in an upcoming update._
- The creation date of the file (not the entry).
- Generated from `st_birthtime` on Windows and Mac, and `st_ctime` on Linux.
- `date_modified` (`DATETIME`/`Datetime`)
- _Not currently used, will be implemented in an upcoming update._
- The latest modification date of the file (not the entry).
- Generated from `st_mtime`.
- `date_added` (`DATETIME`/`Datetime`)
- The date the file entry was added to the TagStudio library.
- `id` (`INTEGER`/`int`, `UNIQUE`, `NOT NULL`, `PRIMARY KEY`)
- The ID for the file entry.
- Used for guaranteed unique references.
- `folder` (`INTEGER`/`int`, `NOT NULL`, `FOREIGN KEY`)
- _Not currently used, may be removed._
- `path` (`VARCHAR`/`Path`, `UNIQUE`, `NOT NULL`)
- The filename and filepath relative to the root of the library folder.
- (E.g. for library "Folder", path = "any_subfolders/filename.txt")
- `suffix` (`VARCHAR`/`str`, `NOT NULL`)
- The filename suffix with no leading dot.
- Used for quicker file extension checks.
- `date_created` (`DATETIME`/`Datetime`)
- _Not currently used, will be implemented in an upcoming update._
- The creation date of the file (not the entry).
- Generated from `st_birthtime` on Windows and Mac, and `st_ctime` on Linux.
- `date_modified` (`DATETIME`/`Datetime`)
- _Not currently used, will be implemented in an upcoming update._
- The latest modification date of the file (not the entry).
- Generated from `st_mtime`.
- `date_added` (`DATETIME`/`Datetime`)
- The date the file entry was added to the TagStudio library.
### Table Relationships
- `tag_entries`
- A relationship between `entry_id` to `tag_id`s from the `tags` table.
- `text_fields`
- (TODO: determine the relationship for `entry_id`)
- `datetime_fields`
- (TODO: determine the relationship for `entry_id`)
- `tag_entries`
- A relationship between `entry_id` to `tag_id`s from the `tags` table.
- `text_fields`
- (TODO: determine the relationship for `entry_id`)
- `datetime_fields`
- (TODO: determine the relationship for `entry_id`)

7
docs/fields.md
View File

@@ -1,6 +1,7 @@
---
icon: material/text-box
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->
@@ -14,16 +15,16 @@ Fields are additional types of metadata that you can attach to [file entries](./
A string of text, displayed as a single line.
- e.g: Title, Author, Artist, URL, etc.
- e.g: Title, Author, Artist, URL, etc.
### Text Box
A long string of text displayed as a box of text.
- e.g: Description, Notes, etc.
- e.g: Description, Notes, etc.
### Datetime
A date and time value.
- e.g: Date Published, Date Taken, etc.
- e.g: Date Published, Date Taken, etc.

2
docs/help/ffmpeg.md
View File

@@ -1,6 +1,7 @@
---
icon: material/movie-open-cog
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->
@@ -25,7 +26,6 @@ To Install:
1. Download 7z or zip file and extract it (right click > Extract All)
2. Move extracted contents to a unique folder (i.e; `c:\ffmpeg` or `c:\Program Files\ffmpeg`)
3. Add FFmpeg to your system PATH
1. In Windows, search for or go to "Edit the system environment variables" under the Control Panel
2. Under "User Variables", select "Path" then edit
3. Click new and add `<Your folder>\bin` (e.g; `c:\ffmpeg\bin` or `c:\Program Files\ffmpeg\bin`)

19
docs/ignore.md
View File

@@ -2,6 +2,7 @@
title: Ignoring Files
icon: material/file-document-remove
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->
@@ -64,7 +65,7 @@ When scanning your library directories, the `.ts_ignore` file is read by either
A `#` symbol at the start of a line indicates that this line is a comment, and match no items. Blank lines are used to enhance readability and also match no items.
- Can be escaped by putting a backslash ("`\`") in front of the `#` symbol.
- Can be escaped by putting a backslash ("`\`") in front of the `#` symbol.
<!-- prettier-ignore-start -->
=== "Example comment"
@@ -106,9 +107,9 @@ A `#` symbol at the start of a line indicates that this line is a comment, and m
The forward slash "`/`" is used as the directory separator. Separators may occur at the beginning, middle or end of the `.ts_ignore` search pattern.
- If there is a separator at the beginning or middle (or both) of the pattern, then the pattern is relative to the directory level of the particular `.TagStudio` library folder itself. Otherwise the pattern may also match at any level below the `.TagStudio` folder level.
- If there is a separator at the beginning or middle (or both) of the pattern, then the pattern is relative to the directory level of the particular `.TagStudio` library folder itself. Otherwise the pattern may also match at any level below the `.TagStudio` folder level.
- If there is a separator at the end of the pattern then the pattern will only match directories, otherwise the pattern can match both files and directories.
- If there is a separator at the end of the pattern then the pattern will only match directories, otherwise the pattern can match both files and directories.
<!-- prettier-ignore-start -->
=== "Example folder pattern"
@@ -129,8 +130,8 @@ The forward slash "`/`" is used as the directory separator. Separators may occur
A `!` prefix before a pattern negates the pattern, allowing any files matched matched by previous patterns to be un-matched.
- Any matching file excluded by a previous pattern will become included again.
- **It is not possible to re-include a file if a parent directory of that file is excluded.**
- Any matching file excluded by a previous pattern will become included again.
- **It is not possible to re-include a file if a parent directory of that file is excluded.**
<!-- prettier-ignore-start -->
=== "Example negation"
@@ -204,10 +205,10 @@ The character "`?`" matches any one character except "`/`".
Two consecutive asterisks ("`**`") in patterns matched against full pathname may have special meaning:
- A leading "`**`" followed by a slash means matches in all directories.
- A trailing "`/**`" matches everything inside.
- A slash followed by two consecutive asterisks then a slash ("`/**/`") matches zero or more directories.
- Other consecutive asterisks are considered regular asterisks and will match according to the previous rules.
- A leading "`**`" followed by a slash means matches in all directories.
- A trailing "`/**`" matches everything inside.
- A slash followed by two consecutive asterisks then a slash ("`/**/`") matches zero or more directories.
- Other consecutive asterisks are considered regular asterisks and will match according to the previous rules.
<!-- prettier-ignore-start -->
=== "Leading **"

37
docs/index.md
View File

@@ -4,6 +4,7 @@ hide:
- toc
- navigation
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->
@@ -38,7 +39,7 @@ hide:
<div class="grid cards" markdown>
- :material-file-multiple:{ .lg .middle } **[All Files](entries.md) Welcome**
- :material-file-multiple:{ .lg .middle } **[All Files](entries.md) Welcome**
***
@@ -46,27 +47,25 @@ hide:
[:material-arrow-right: See Full Preview Support](preview-support.md)
- :material-tag-text:{ .lg .middle } **Create [Tags](tags.md) Your Way**
- :material-tag-text:{ .lg .middle } **Create [Tags](tags.md) Your Way**
***
- :material-format-font: No character restrictions
- :material-form-textbox: Add aliases/alternate names
- :material-palette: Customize colors and styles
- :material-tag-multiple: Tags can be tagged with other tags!
- :material-star-four-points: And more!
- :material-format-font: No character restrictions
- :material-form-textbox: Add aliases/alternate names
- :material-palette: Customize colors and styles
- :material-tag-multiple: Tags can be tagged with other tags!
- :material-star-four-points: And more!
- :material-magnify:{ .lg .middle } **Powerful [Search](search.md)**
- :material-magnify:{ .lg .middle } **Powerful [Search](search.md)**
***
- Full [Boolean operator](search.md) support
- Filenames, paths, and extensions with [glob](<https://en.wikipedia.org/wiki/Glob_(programming)>) syntax
- General media types (e.g. "Photo", "Video", "Document")
- Special searches (e.g. "Untagged")
- "[Smartcase](search.md#case-sensitivity)" case sensitivity
- Full [Boolean operator](search.md) support
- Filenames, paths, and extensions with [glob](<https://en.wikipedia.org/wiki/Glob_(programming)>) syntax
- General media types (e.g. "Photo", "Video", "Document")
- Special searches (e.g. "Untagged")
- "[Smartcase](search.md#case-sensitivity)" case sensitivity
- :material-text-box:{ .lg .middle } **Text and Date [Fields](fields.md)**
- :material-text-box:{ .lg .middle } **Text and Date [Fields](fields.md)**
***
@@ -80,7 +79,7 @@ hide:
<div class="grid cards" markdown>
- :material-scale-balance:{ .lg .middle } **Open Source**
- :material-scale-balance:{ .lg .middle } **Open Source**
***
@@ -90,7 +89,7 @@ hide:
[:material-arrow-right: Roadmap to MIT Core Library License](roadmap.md#core-library-api)
- :material-database:{ .lg .middle } **Central Save File**
- :material-database:{ .lg .middle } **Central Save File**
***
@@ -108,6 +107,6 @@ TagStudio aims to create an **open** and **robust** format for file tagging that
<div class="grid cards" markdown>
- :material-map-check:{ .lg .middle } See the [**Roadmap**](roadmap.md) for future features and updates
- :material-map-check:{ .lg .middle } See the [**Roadmap**](roadmap.md) for future features and updates
</div>

38
docs/install.md
View File

@@ -1,6 +1,7 @@
---
icon: material/download
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->
@@ -64,22 +65,21 @@ TagStudio can now be launched via the `tagstudio` command in your terminal.
Some external dependencies are required for TagStudio to execute. Below is a table of known packages that will be necessary.
<!-- prettier-ignore -->
| Package | Reason |
|--------------- | --------------- |
| [dbus](https://repology.org/project/dbus) | required for Qt; opening desktop applications |
| [ffmpeg](https://repology.org/project/ffmpeg) | audio/video playback |
| libstdc++ | required for Qt |
| [libva](https://repology.org/project/libva) | hardware rendering with [VAAPI](https://www.freedesktop.org/wiki/Software/vaapi) |
| [libvdpau](https://repology.org/project/libvdpau) | hardware rendering with [VDPAU](https://www.freedesktop.org/wiki/Software/VDPAU) |
| [libx11](https://repology.org/project/libx11) | required for Qt |
| libxcb-cursor OR [xcb-util-cursor](https://repology.org/project/xcb-util-cursor) | required for Qt |
| [libxkbcommon](https://repology.org/project/libxkbcommon) | required for Qt |
| [libxrandr](https://repology.org/project/libxrandr) | hardware rendering |
| [pipewire](https://repology.org/project/pipewire) | PipeWire audio support |
| [qt](https://repology.org/project/qt) | required |
| [qt-multimedia](https://repology.org/project/qt) | required |
| [qt-wayland](https://repology.org/project/qt) | Wayland support |
| Package | Reason |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [dbus](https://repology.org/project/dbus) | required for Qt; opening desktop applications |
| [ffmpeg](https://repology.org/project/ffmpeg) | audio/video playback |
| libstdc++ | required for Qt |
| [libva](https://repology.org/project/libva) | hardware rendering with [VAAPI](https://www.freedesktop.org/wiki/Software/vaapi) |
| [libvdpau](https://repology.org/project/libvdpau) | hardware rendering with [VDPAU](https://www.freedesktop.org/wiki/Software/VDPAU) |
| [libx11](https://repology.org/project/libx11) | required for Qt |
| libxcb-cursor OR [xcb-util-cursor](https://repology.org/project/xcb-util-cursor) | required for Qt |
| [libxkbcommon](https://repology.org/project/libxkbcommon) | required for Qt |
| [libxrandr](https://repology.org/project/libxrandr) | hardware rendering |
| [pipewire](https://repology.org/project/pipewire) | PipeWire audio support |
| [qt](https://repology.org/project/qt) | required |
| [qt-multimedia](https://repology.org/project/qt) | required |
| [qt-wayland](https://repology.org/project/qt) | Wayland support |
### :material-nix: Nix(OS)
@@ -225,15 +225,15 @@ For audio/video thumbnails and playback you'll need [FFmpeg](https://ffmpeg.org/
To generate thumbnails for RAR-based files (like `.cbr`) you'll need an extractor capable of handling them.
- :material-penguin: On Linux you'll need to install either `unrar` (likely in you distro's non-free repository) or `unrar-free` from your package manager.
- :material-penguin: On Linux you'll need to install either `unrar` (likely in you distro's non-free repository) or `unrar-free` from your package manager.
- :fontawesome-brands-apple: On macOS `unrar` can be installed through Homebrew's [`rar`](https://formulae.brew.sh/cask/rar) formula.
- :fontawesome-brands-apple: On macOS `unrar` can be installed through Homebrew's [`rar`](https://formulae.brew.sh/cask/rar) formula.
<!-- prettier-ignore -->
!!! warning ":fontawesome-brands-apple: macOS "Privacy & Security" Popup"
On macOS, you may be met with a message similar to "**"unrar" Not Opened. Apple could not verify "unrar" is free of malware that may harm your Mac or compromise your privacy**" If you encounter this, then you'll need to go to the "Settings" app, navigate to "Privacy & Security", and scroll down to a section that says "**"unrar" was blocked from use because it is not from an identified developer.**" Click the "Open Anyway" button to allow unrar to be used.
- :fontawesome-brands-windows: On Windows you'll need to install either [`WinRAR`](https://www.rarlab.com/download.htm) or [`7-zip`](https://www.7-zip.org/) and add their folder to you `PATH`.
- :fontawesome-brands-windows: On Windows you'll need to install either [`WinRAR`](https://www.rarlab.com/download.htm) or [`7-zip`](https://www.7-zip.org/) and add their folder to you `PATH`.
<!-- prettier-ignore -->
!!! tip "WinRAR License"

1
docs/libraries.md
View File

@@ -1,6 +1,7 @@
---
icon: material/database
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->

1
docs/library-changes.md
View File

@@ -1,6 +1,7 @@
---
icon: material/database-edit
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->

1
docs/macros.md
View File

@@ -1,6 +1,7 @@
---
icon: material/script-text
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->

5
docs/preview-support.md
View File

@@ -1,6 +1,7 @@
---
icon: material/image-check
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->
@@ -81,7 +82,7 @@ Audio thumbnails will default to embedded cover art (if any) and fallback to gen
Preview support for office documents or well-known project file formats varies by the format and whether or not embedded thumbnails are available to be read from. OpenDocument-based files are typically supported.
| Filetype | Extensions | Preview Type |
|--------------------------------------| --------------------- | -------------------------------------------------------------------------- |
| ------------------------------------ | --------------------- | -------------------------------------------------------------------------- |
| Blender | `.blend`, `.blend<#>` | Embedded thumbnail :material-alert-circle:{ title="If available in file" } |
| Clip Studio Paint | `.clip` | Embedded thumbnail |
| Keynote (Apple iWork) | `.key` | Embedded thumbnail |
@@ -103,7 +104,7 @@ Preview support for office documents or well-known project file formats varies b
Archive thumbnails will display the first image from the archive within the Preview Panel.
| Filetype | Extensions |
|----------|----------------|
| -------- | -------------- |
| 7-Zip | `.7z`, `.s7z` |
| RAR | `.rar` |
| Tar | `.tar`, `.tgz` |

383
docs/roadmap.md
View File

@@ -1,6 +1,7 @@
---
icon: material/map-check
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->
@@ -16,9 +17,9 @@ Planned features and changes are assigned **priority levels** to signify how imp
<!-- prettier-ignore -->
!!! info "Priority Level Icons"
- :material-chevron-triple-up:{ .priority-high title="High Priority" } **High Priority** - Core features
- :material-chevron-double-up:{ .priority-med title="Medium Priority" } **Medium Priority** - Important, but not necessary
- :material-chevron-up:{ .priority-low title="Low Priority" } **Low Priority** - Just nice to have
- :material-chevron-triple-up:{ .priority-high title="High Priority" } **High Priority** - Core features
- :material-chevron-double-up:{ .priority-med title="Medium Priority" } **Medium Priority** - Important, but not necessary
- :material-chevron-up:{ .priority-low title="Low Priority" } **Low Priority** - Just nice to have
## Version Estimates
@@ -41,29 +42,29 @@ Must be finalized or deemed "feature complete" before other core features are de
!!! note
See the "[Library](#library)" section for features related to the library database rather than the underlying schema.
- [x] A SQLite-based library save file format **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [ ] Cached File Properties Table :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [x] Date Entry Added to Library :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Date File Created :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Date File Modified :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Date Photo Taken :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Media Duration :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Media Dimensions :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Word Count :material-chevron-up:{ .priority-low title="Low Priority" }
- [x] A SQLite-based library save file format **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [ ] Cached File Properties Table :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [x] Date Entry Added to Library :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Date File Created :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Date File Modified :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Date Photo Taken :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Media Duration :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Media Dimensions :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Word Count :material-chevron-up:{ .priority-low title="Low Priority" }
### :material-database-cog: Core Library + API
A separated, UI agnostic core library that would be used to interface with the TagStudio library format. Would host an API for communication from outside the program. This would be licensed under the more permissive [MIT](https://en.wikipedia.org/wiki/MIT_License) license to foster wider adoption compared to the TagStudio application source code.
- [ ] Core Library :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v10.0.0]**
- [ ] Core Library API :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v10.0.0]**
- [ ] MIT License :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v10.0.0]**
- [ ] Core Library :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v10.0.0]**
- [ ] Core Library API :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v10.0.0]**
- [ ] MIT License :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v10.0.0]**
### :material-clipboard-text: Format Specification
A detailed written specification for the TagStudio tag and/or library format. Intended for used by third-parties to build alternative cores or protocols that can remain interoperable.
- [ ] Format Specification Established :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v10.0.0]**
- [ ] Format Specification Established :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v10.0.0]**
---
@@ -71,74 +72,74 @@ A detailed written specification for the TagStudio tag and/or library format. In
### :material-button-cursor: UI/UX
- [x] Library Grid View
- [ ] Explore Filesystem in Grid View :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Infinite Scrolling (No Pagination) :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Library List View :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Explore Filesystem in List View :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Lightbox View :material-chevron-triple-up:{ .priority-high title="High Priority" }
- Similar to List View in concept, but displays one large preview that can cycle back/forth between entries.
- [ ] Smaller thumbnails of immediate adjacent entries below :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [x] Library Statistics Screen **[[v9.5.4](changelog.md#954-september-1st-2025)]**
- [x] Unified Library Health/Cleanup Screen **[[v9.5.4](changelog.md#954-september-1st-2025)]**
- [x] Fix Unlinked Entries
- [x] Fix Duplicate Files
- [x] ~~Fix Duplicate Entries~~
- [x] Remove Ignored Entries **[[v9.5.4](changelog.md#954-september-1st-2025)]**
- [x] Delete Old Backups **[[v9.5.4](changelog.md#954-september-1st-2025)]**
- [x] Delete Legacy JSON File **[[v9.5.4](changelog.md#954-september-1st-2025)]**
- [x] Translations
- [ ] Search Bar Rework :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.7.x]**
- [ ] Improved Tag Autocomplete :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Tags appear as widgets in search bar :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [x] Unified Media Player
- [x] Auto-Hiding Player Controls
- [x] Play/Pause
- [x] Loop
- [x] Toggle Autoplay
- [x] Volume Control
- [x] Toggle Mute
- [x] Timeline scrubber
- [ ] Fullscreen :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Fine-Tuned UI/UX :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6]**
- [ ] 3D Model Thumbnails/Previews :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] STL File Support
- [ ] OBJ File Support
- [ ] Plaintext Thumbnails/Previews :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [x] Basic Support
- [ ] Full File Preview :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Syntax Highlighting :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Toggleable Persistent Tagging Panel :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Top Tags
- [ ] Recent Tags
- [ ] Tag Search
- [ ] Pinned Tags
- [ ] New Tabbed Tag Building UI to Support New Tag Features :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Custom Thumbnail Overrides :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Media Duration Labels :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Word/Line Count Labels :material-chevron-up:{ .priority-low title="Low Priority" }
- [ ] Custom Tag Badges :material-chevron-up:{ .priority-low title="Low Priority" }
- Would serve as an addition/alternative to the Favorite and Archived badges.
- [x] Library Grid View
- [ ] Explore Filesystem in Grid View :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Infinite Scrolling (No Pagination) :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Library List View :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Explore Filesystem in List View :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Lightbox View :material-chevron-triple-up:{ .priority-high title="High Priority" }
- Similar to List View in concept, but displays one large preview that can cycle back/forth between entries.
- [ ] Smaller thumbnails of immediate adjacent entries below :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [x] Library Statistics Screen **[[v9.5.4](changelog.md#954-september-1st-2025)]**
- [x] Unified Library Health/Cleanup Screen **[[v9.5.4](changelog.md#954-september-1st-2025)]**
- [x] Fix Unlinked Entries
- [x] Fix Duplicate Files
- [x] ~~Fix Duplicate Entries~~
- [x] Remove Ignored Entries **[[v9.5.4](changelog.md#954-september-1st-2025)]**
- [x] Delete Old Backups **[[v9.5.4](changelog.md#954-september-1st-2025)]**
- [x] Delete Legacy JSON File **[[v9.5.4](changelog.md#954-september-1st-2025)]**
- [x] Translations
- [ ] Search Bar Rework :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.7.x]**
- [ ] Improved Tag Autocomplete :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Tags appear as widgets in search bar :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [x] Unified Media Player
- [x] Auto-Hiding Player Controls
- [x] Play/Pause
- [x] Loop
- [x] Toggle Autoplay
- [x] Volume Control
- [x] Toggle Mute
- [x] Timeline scrubber
- [ ] Fullscreen :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Fine-Tuned UI/UX :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6]**
- [ ] 3D Model Thumbnails/Previews :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] STL File Support
- [ ] OBJ File Support
- [ ] Plaintext Thumbnails/Previews :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [x] Basic Support
- [ ] Full File Preview :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Syntax Highlighting :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Toggleable Persistent Tagging Panel :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Top Tags
- [ ] Recent Tags
- [ ] Tag Search
- [ ] Pinned Tags
- [ ] New Tabbed Tag Building UI to Support New Tag Features :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Custom Thumbnail Overrides :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Media Duration Labels :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Word/Line Count Labels :material-chevron-up:{ .priority-low title="Low Priority" }
- [ ] Custom Tag Badges :material-chevron-up:{ .priority-low title="Low Priority" }
- Would serve as an addition/alternative to the Favorite and Archived badges.
### :material-cog: Settings
- [x] Application Settings
- [x] Stored in System User Folder/Designated Folder
- [x] Language
- [x] Date and Time Format
- [x] Theme
- [x] Thumbnail Generation **[[v9.5.4](changelog.md#954-september-1st-2025)]**
- [x] Configurable Page Size
- [ ] Library Settings :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Stored in `.TagStudio` folder :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Toggle File Extension Label :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Toggle Duration Label :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [x] Application Settings
- [x] Stored in System User Folder/Designated Folder
- [x] Language
- [x] Date and Time Format
- [x] Theme
- [x] Thumbnail Generation **[[v9.5.4](changelog.md#954-september-1st-2025)]**
- [x] Configurable Page Size
- [ ] Library Settings :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Stored in `.TagStudio` folder :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Toggle File Extension Label :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Toggle Duration Label :material-chevron-double-up:{ .priority-med title="Medium Priority" }
### :material-puzzle: Plugin Support
Some form of official plugin support for TagStudio, likely with its own API that may connect to or encapsulate part of the the [core library API](#core-library-api).
- [ ] Plugin Support :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v10.0.0]**
- [ ] Plugin Support :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v10.0.0]**
---
@@ -146,140 +147,140 @@ Some form of official plugin support for TagStudio, likely with its own API that
### :material-wrench: Library Mechanics
- [x] Per-Library Tags
- [ ] Global Tags :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Multiple Root Directories :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Ability to store TagStudio library folder separate from library files :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Automatic Entry Relinking :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.7.x]**
- [ ] Detect Renames :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Detect Moves :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Detect Deletions :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Performant :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Background File Scanning :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.7.x]**
- [x] Thumbnail Caching **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [ ] Audio Waveform Caching :material-chevron-double-up:{ .priority-med title="Medium Priority" } **[v9.7.x]**
- [x] Per-Library Tags
- [ ] Global Tags :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Multiple Root Directories :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Ability to store TagStudio library folder separate from library files :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Automatic Entry Relinking :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.7.x]**
- [ ] Detect Renames :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Detect Moves :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Detect Deletions :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Performant :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Background File Scanning :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.7.x]**
- [x] Thumbnail Caching **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [ ] Audio Waveform Caching :material-chevron-double-up:{ .priority-med title="Medium Priority" } **[v9.7.x]**
### :material-grid: [Entries](entries.md)
Library representations of files or file-like objects.
- [x] File Entries **[v1.0.0]**
- [ ] Folder Entries :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] URL Entries / Bookmarks :material-chevron-up:{ .priority-low title="Low Priority" }
- [x] Fields
- [x] Text Lines
- [x] Text Boxes
- [x] Datetimes **[[v9.5.4](changelog.md#954-september-1st-2025)]**
- [ ] User-Titled Fields :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Removal of Deprecated Fields :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Entry Groups :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.7.x]**
- [ ] Non-exclusive; Entries can be in multiple groups :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Ability to number entries within group :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Ability to set sorting method for group :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Ability to set custom thumbnail for group :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Group is treated as entry with tags and metadata :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Nested groups :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [x] File Entries **[v1.0.0]**
- [ ] Folder Entries :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] URL Entries / Bookmarks :material-chevron-up:{ .priority-low title="Low Priority" }
- [x] Fields
- [x] Text Lines
- [x] Text Boxes
- [x] Datetimes **[[v9.5.4](changelog.md#954-september-1st-2025)]**
- [ ] User-Titled Fields :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Removal of Deprecated Fields :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Entry Groups :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.7.x]**
- [ ] Non-exclusive; Entries can be in multiple groups :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Ability to number entries within group :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Ability to set sorting method for group :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Ability to set custom thumbnail for group :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Group is treated as entry with tags and metadata :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Nested groups :material-chevron-double-up:{ .priority-med title="Medium Priority" }
### :material-tag-text: [Tags](tags.md)
Discrete library objects representing [attributes](<https://en.wikipedia.org/wiki/Property_(philosophy)>). Can be applied to library [entries](entries.md), or applied to other tags to build traversable relationships.
- [x] Tag Name **[v8.0.0]**
- [x] Tag Shorthand Name **[v8.0.0]**
- [x] Tag Aliases List **[v8.0.0]**
- [x] Tag Color **[v8.0.0]**
- [ ] Tag Description :material-chevron-double-up:{ .priority-med title="Medium Priority" } **[v9.6.x]**
- [x] Tag Colors
- [x] Built-in Color Palette **[v8.0.0]**
- [x] User-Defined Colors **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] Primary and Secondary Colors **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [ ] Tag Icons :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Small Icons :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Large Icons for Profiles :material-chevron-double-up:{ .priority-med title="Medium Priority" } **[v9.6.x]**
- [ ] Built-in Icon Packs (i.e. Boxicons) :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] User-Defined Icons :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [x] [Category Property](tags.md#is-category) **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] Property available for tags that allow the tag and any inheriting from it to be displayed separately in the preview panel under a title
- [ ] Fine-tuned exclusion from categories :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Hidden Property :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Built-in "Archived" tag has this property by default :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Checkbox near search bar to show hidden tags in search :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Tag Relationships
- [x] [Parent Tags](tags.md#parent-tags) ([Inheritance](<https://en.wikipedia.org/wiki/Inheritance_(object-oriented_programming)>) Relationship) **[v9.0.0]**
- [ ] [Component Tags](tags.md#component-tags) ([Composition](https://en.wikipedia.org/wiki/Object_composition) Relationship) :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Multiple Language Support :material-chevron-up:{ .priority-low title="Low Priority" } **[v9.9.x]**
- [ ] Tag Overrides :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Tag Merging :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [x] Tag Name **[v8.0.0]**
- [x] Tag Shorthand Name **[v8.0.0]**
- [x] Tag Aliases List **[v8.0.0]**
- [x] Tag Color **[v8.0.0]**
- [ ] Tag Description :material-chevron-double-up:{ .priority-med title="Medium Priority" } **[v9.6.x]**
- [x] Tag Colors
- [x] Built-in Color Palette **[v8.0.0]**
- [x] User-Defined Colors **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] Primary and Secondary Colors **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [ ] Tag Icons :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Small Icons :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Large Icons for Profiles :material-chevron-double-up:{ .priority-med title="Medium Priority" } **[v9.6.x]**
- [ ] Built-in Icon Packs (i.e. Boxicons) :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] User-Defined Icons :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [x] [Category Property](tags.md#is-category) **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] Property available for tags that allow the tag and any inheriting from it to be displayed separately in the preview panel under a title
- [ ] Fine-tuned exclusion from categories :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Hidden Property :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Built-in "Archived" tag has this property by default :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Checkbox near search bar to show hidden tags in search :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Tag Relationships
- [x] [Parent Tags](tags.md#parent-tags) ([Inheritance](<https://en.wikipedia.org/wiki/Inheritance_(object-oriented_programming)>) Relationship) **[v9.0.0]**
- [ ] [Component Tags](tags.md#component-tags) ([Composition](https://en.wikipedia.org/wiki/Object_composition) Relationship) :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Multiple Language Support :material-chevron-up:{ .priority-low title="Low Priority" } **[v9.9.x]**
- [ ] Tag Overrides :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Tag Merging :material-chevron-double-up:{ .priority-med title="Medium Priority" }
### :material-magnify: [Search](search.md)
- [x] Tag Search **[v8.0.0]**
- [x] Filename Search **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] Glob Search **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] Filetype Search **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] Search by Extension (e.g. ".jpg", ".png") **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] Optional consolidation of extension synonyms (i.e. ".jpg" can equal ".jpeg") **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] Search by media type (e.g. "image", "video", "document") **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [ ] Field Content Search :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [x] [Boolean Operators](search.md) **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] `AND` Operator
- [x] `OR` Operator
- [x] `NOT` Operator
- [x] Parenthesis Grouping
- [x] Character Escaping
- [ ] `HAS` Operator (for [Component Tags](tags.md#component-tags)) :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Conditional Search :material-chevron-double-up:{ .priority-med title="Medium Priority" } **[v9.7.x]**
- [ ] Compare Dates :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Compare Durations :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Compare File Sizes :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Compare Dimensions :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [x] Smartcase Search **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [ ] Search Result Sorting
- [x] Sort by Filename **[[v9.5.2](changelog.md#952-march-31st-2025)]**
- [x] Sort by Date Entry Added to Library **[[v9.5.2](changelog.md#952-march-31st-2025)]**
- [ ] Sort by File Creation Date :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Sort by File Modification Date :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Sort by File Modification Date :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Sort by Date Taken (Photos) :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [x] Random/Shuffle Sort
- [ ] OCR Search :material-chevron-up:{ .priority-low title="Low Priority" }
- [ ] Fuzzy Search :material-chevron-up:{ .priority-low title="Low Priority" }
- [x] Tag Search **[v8.0.0]**
- [x] Filename Search **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] Glob Search **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] Filetype Search **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] Search by Extension (e.g. ".jpg", ".png") **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] Optional consolidation of extension synonyms (i.e. ".jpg" can equal ".jpeg") **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] Search by media type (e.g. "image", "video", "document") **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [ ] Field Content Search :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [x] [Boolean Operators](search.md) **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [x] `AND` Operator
- [x] `OR` Operator
- [x] `NOT` Operator
- [x] Parenthesis Grouping
- [x] Character Escaping
- [ ] `HAS` Operator (for [Component Tags](tags.md#component-tags)) :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Conditional Search :material-chevron-double-up:{ .priority-med title="Medium Priority" } **[v9.7.x]**
- [ ] Compare Dates :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Compare Durations :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Compare File Sizes :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Compare Dimensions :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [x] Smartcase Search **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
- [ ] Search Result Sorting
- [x] Sort by Filename **[[v9.5.2](changelog.md#952-march-31st-2025)]**
- [x] Sort by Date Entry Added to Library **[[v9.5.2](changelog.md#952-march-31st-2025)]**
- [ ] Sort by File Creation Date :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Sort by File Modification Date :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [ ] Sort by File Modification Date :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Sort by Date Taken (Photos) :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
- [x] Random/Shuffle Sort
- [ ] OCR Search :material-chevron-up:{ .priority-low title="Low Priority" }
- [ ] Fuzzy Search :material-chevron-up:{ .priority-low title="Low Priority" }
### :material-file-cog: [Macros](macros.md)
- [ ] Standard, Human Readable Format (TOML) :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.5.x]**
- [ ] Versioning System :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.5.x]**
- [ ] Triggers **[v9.5.x]**
- [ ] On File Added :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] On Library Refresh :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] [...]
- [ ] Actions **[v9.5.x]**
- [ ] Add Tag(s) :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Add Field(s) :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Set Field Content :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] [...]
- [ ] Standard, Human Readable Format (TOML) :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.5.x]**
- [ ] Versioning System :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.5.x]**
- [ ] Triggers **[v9.5.x]**
- [ ] On File Added :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] On Library Refresh :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] [...]
- [ ] Actions **[v9.5.x]**
- [ ] Add Tag(s) :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Add Field(s) :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Set Field Content :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] [...]
### :material-table-arrow-right: Sharable Data
Sharable TagStudio library data in the form of data packs (tags, colors, etc.) or other formats.
Packs are intended as an easy way to import and export specific data between libraries and users, while export-only formats are intended to be imported by other programs.
- [ ] Color Packs :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.5.x]**
- [ ] Importable
- [ ] Exportable
- [x] UUIDs + Namespaces :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [x] Standard, Human Readable Format (TOML) :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Versioning System :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Tag Packs :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.9.x]**
- [ ] Importable :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Exportable :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] UUIDs + Namespaces :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Standard, Human Readable Format (TOML) :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Versioning System :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Macro Sharing :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.5.x]**
- [ ] Importable :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Exportable :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Sharable Entry Data :material-chevron-double-up:{ .priority-med title="Medium Priority" } **[v9.9.x]**
- _Specifics of this are yet to be determined_
- [ ] Export Library to Human Readable Format :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v10.0.0]**
- Intended to give users more flexible options with their data if they wish to migrate away from TagStudio
- [ ] Color Packs :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.5.x]**
- [ ] Importable
- [ ] Exportable
- [x] UUIDs + Namespaces :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [x] Standard, Human Readable Format (TOML) :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Versioning System :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Tag Packs :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.9.x]**
- [ ] Importable :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Exportable :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] UUIDs + Namespaces :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Standard, Human Readable Format (TOML) :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Versioning System :material-chevron-double-up:{ .priority-med title="Medium Priority" }
- [ ] Macro Sharing :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.5.x]**
- [ ] Importable :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Exportable :material-chevron-triple-up:{ .priority-high title="High Priority" }
- [ ] Sharable Entry Data :material-chevron-double-up:{ .priority-med title="Medium Priority" } **[v9.9.x]**
- _Specifics of this are yet to be determined_
- [ ] Export Library to Human Readable Format :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v10.0.0]**
- Intended to give users more flexible options with their data if they wish to migrate away from TagStudio

53
docs/search.md
View File

@@ -1,6 +1,7 @@
---
icon: material/magnify
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->
@@ -50,13 +51,13 @@ Sometimes search queries have ambiguous characters and need to be "escaped". Thi
#### Valid Escaped Tag Searches
- "Tag Name With Spaces"
- Tag_Name_With_Spaces
- "Tag Name With Spaces"
- Tag_Name_With_Spaces
#### Invalid Escaped Tag Searches
- Tag Name With Spaces
- Reason: Ambiguity between a tag named "Tag Name With Spaces" and four individual tags called "Tag", "Name", "With", "Spaces".
- Tag Name With Spaces
- Reason: Ambiguity between a tag named "Tag Name With Spaces" and four individual tags called "Tag", "Name", "With", "Spaces".
## Tags
@@ -86,31 +87,31 @@ Optionally, you may use [glob](<https://en.wikipedia.org/wiki/Glob_(programming)
Given a file "Artwork/Piece.jpg", the following searches will return results for it:
- `path: artwork/piece.jpg`
- `path: Artwork/Piece.jpg`
- `path: piece.jpg`
- `path: Piece.jpg`
- `path: artwork`
- `path: rtwor`
- `path: ece.jpg`
- `path: iec`
- `path: artwork/*`
- `path: Artwork/*`
- `path: *piece.jpg*`
- `path: *Piece.jpg*`
- `path: *artwork*`
- `path: *Artwork*`
- `path: *rtwor*`
- `path: *ece.jpg*`
- `path: *iec*`
- `path: *.jpg`
- `path: artwork/piece.jpg`
- `path: Artwork/Piece.jpg`
- `path: piece.jpg`
- `path: Piece.jpg`
- `path: artwork`
- `path: rtwor`
- `path: ece.jpg`
- `path: iec`
- `path: artwork/*`
- `path: Artwork/*`
- `path: *piece.jpg*`
- `path: *Piece.jpg*`
- `path: *artwork*`
- `path: *Artwork*`
- `path: *rtwor*`
- `path: *ece.jpg*`
- `path: *iec*`
- `path: *.jpg`
While the following searches will **NOT:**
- `path: ARTWORK/Piece.jpg` _(Reason: Mismatched case)_
- `path: *aRtWoRk/Piece*` _(Reason: Mismatched case)_
- `path: PieCe.jpg` _(Reason: Mismatched case)_
- `path: *PieCe.jpg*` _(Reason: Mismatched case)_
- `path: ARTWORK/Piece.jpg` _(Reason: Mismatched case)_
- `path: *aRtWoRk/Piece*` _(Reason: Mismatched case)_
- `path: PieCe.jpg` _(Reason: Mismatched case)_
- `path: *PieCe.jpg*` _(Reason: Mismatched case)_
## Special Searches

42
docs/style.md
View File

@@ -1,6 +1,7 @@
---
icon: material/sign-text
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->
@@ -10,20 +11,21 @@ icon: material/sign-text
Most of the style guidelines can be checked, fixed, and enforced via Ruff. Older code may not be adhering to all of these guidelines, in which case _"do as I say, not as I do"..._
- Do your best to write clear, concise, and modular code.
- This should include making methods private by default (e.g. `__method()`)
- Methods should only be protected (e.g. `_method()`) or public (e.g. `method()`) when needed and warranted
- Keep a maximum column width of no more than **100** characters.
- Code comments should be used to help describe sections of code that can't speak for themselves.
- Use [Google style](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings) docstrings for any classes and functions you add.
- If you're modifying an existing function that does _not_ have docstrings, you don't _have_ to add docstrings to it... but it would be pretty cool if you did ;)
- Imports should be ordered alphabetically.
- Lists of values should be ordered using their [natural sort order](https://en.wikipedia.org/wiki/Natural_sort_order).
- Some files have their methods ordered alphabetically as well (i.e. [`thumb_renderer`](https://github.com/TagStudioDev/TagStudio/blob/main/src/tagstudio/qt/widgets/thumb_renderer.py)). If you're working in a file and notice this, please try and keep to the pattern.
- When writing text for window titles or form titles, use "[Title Case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case)" capitalization. Your IDE may have a command to format this for you automatically, although some may incorrectly capitalize short prepositions. In a pinch you can use a website such as [capitalizemytitle.com](https://capitalizemytitle.com/) to check.
- If it wasn't mentioned above, then stick to [**PEP-8**](https://peps.python.org/pep-0008/)!
- Do your best to write clear, concise, and modular code.
- This should include making methods private by default (e.g. `__method()`)
- Methods should only be protected (e.g. `_method()`) or public (e.g. `method()`) when needed and warranted
- Keep a maximum column width of no more than **100** characters.
- Code comments should be used to help describe sections of code that can't speak for themselves.
- Use [Google style](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings) docstrings for any classes and functions you add.
- If you're modifying an existing function that does _not_ have docstrings, you don't _have_ to add docstrings to it... but it would be pretty cool if you did ;)
- Imports should be ordered alphabetically.
- Lists of values should be ordered using their [natural sort order](https://en.wikipedia.org/wiki/Natural_sort_order).
- Some files have their methods ordered alphabetically as well (i.e. [`thumb_renderer`](https://github.com/TagStudioDev/TagStudio/blob/main/src/tagstudio/qt/widgets/thumb_renderer.py)). If you're working in a file and notice this, please try and keep to the pattern.
- When writing text for window titles or form titles, use "[Title Case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case)" capitalization. Your IDE may have a command to format this for you automatically, although some may incorrectly capitalize short prepositions. In a pinch you can use a website such as [capitalizemytitle.com](https://capitalizemytitle.com/) to check.
- If it wasn't mentioned above, then stick to [**PEP-8**](https://peps.python.org/pep-0008/)!
### Formatter Configs
TagStudio provides an [EditorConfig](https://editorconfig.org/#example-file) file ([`.editorconfig`](../.editorconfig)) along with a [Prettier](https://prettier.io/) config file ([`.prettierrc.toml`](../.prettierrc.toml)) for formatting files other than .py files (Markdown, JSON, YAML, HTML, CSS, etc.). If editing these types of files it's recommended that you use a formatter that supports EditorConfig or has its settings matched to the EditorConfig and Prettier configs. Lastly, please pay attention to the `prettier-ignore` flags in present in some files if you are not using Prettier, as formatting these sections will break formatting used elsewhere such as the [MkDocs site](https://docs.tagstud.io/).
## Qt
@@ -85,14 +87,14 @@ class MyCoolWidget(MyCoolWidgetView):
Observe the following key aspects of this example:
- The Controller is just called `MyCoolWidget` instead of `MyCoolWidgetController` as it will be directly used by other code
- The UI elements are in private variables
- This enforces that the controller shouldn't directly access UI elements
- Instead the view should provide a protected API (e.g. `_get_color()`) for things like setting/getting the value of a dropdown, etc.
- Instead of `_get_color()` there could also be a `_color` method marked with `@property`
- The callback methods are already defined as protected methods with NotImplementedErrors
- Defines the interface the callbacks
- Enforces that UI events be handled
- The Controller is just called `MyCoolWidget` instead of `MyCoolWidgetController` as it will be directly used by other code
- The UI elements are in private variables
- This enforces that the controller shouldn't directly access UI elements
- Instead the view should provide a protected API (e.g. `_get_color()`) for things like setting/getting the value of a dropdown, etc.
- Instead of `_get_color()` there could also be a `_color` method marked with `@property`
- The callback methods are already defined as protected methods with NotImplementedErrors
- Defines the interface the callbacks
- Enforces that UI events be handled
<!-- prettier-ignore -->
!!! tip

6
docs/stylesheets/extra.css
View File

@@ -62,11 +62,7 @@
/* Mobile Nav Header */
.md-nav__source {
background: linear-gradient(
60deg,
rgb(205, 78, 255) 0%,
rgb(116, 123, 255) 100%
);
background: linear-gradient(60deg, rgb(205, 78, 255) 0%, rgb(116, 123, 255) 100%);
border-style: solid;
border-width: 0 0 2px 0;
border-color: #ffffff33;

7
docs/tags.md
View File

@@ -1,6 +1,7 @@
---
icon: material/tag-text
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->
@@ -12,9 +13,9 @@ Tags are discrete objects that represent some attribute. This could be a person,
TagStudio tags do not share the same naming limitations of many other tagging solutions. The key standouts of tag names in TagStudio are:
- Tag names do **NOT** have to be unique
- Tag names are **NOT** limited to specific characters
- Tags can have **aliases**, a.k.a. alternate names to go by
- Tag names do **NOT** have to be unique
- Tag names are **NOT** limited to specific characters
- Tags can have **aliases**, a.k.a. alternate names to go by
### Name

17
docs/usage.md
View File

@@ -1,6 +1,7 @@
---
icon: material/mouse
---
<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->
@@ -36,14 +37,14 @@ Hover over the field and click the pencil icon. From there, add or edit text in
Create a new tag by accessing the "New Tag" option from the Edit menu or by pressing <kbd>Ctrl</kbd>+<kbd>T</kbd>. In the tag creation panel, enter a tag name, optional shorthand name, optional tag aliases, optional parent tags, and an optional color.
- The tag **name** is the base name of the tag. **_This does NOT have to be unique!_**
- The tag **shorthand** is a special type of alias that displays in situations where screen space is more valuable, notably with name disambiguation.
- **Aliases** are alternate names for a tag. These let you search for terms other than the exact tag name in order to find the tag again.
- **Parent Tags** are tags in which this tag can substitute for in searches. In other words, tags under this section are parents of this tag.
- Parent tags with the disambiguation check next to them will be used to help disambiguate tag names that may not be unique.
- For example: If you had a tag for "Freddy Fazbear", you might add "Five Nights at Freddy's" as one of the parent tags. If the disambiguation box is checked next to "Five Nights at Freddy's" parent tag, then the tag "Freddy Fazbear" will display as "Freddy Fazbear (Five Nights at Freddy's)". Furthermore, if the "Five Nights at Freddy's" tag has a shorthand like "FNAF", then the "Freddy Fazbear" tag will display as "Freddy Fazbear (FNAF)".
- The **color** option lets you select an optional color palette to use for your tag.
- The **"Is Category"** property lets you treat this tag as a category under which itself and any child tags inheriting from it will be sorted by inside the preview panel.
- The tag **name** is the base name of the tag. **_This does NOT have to be unique!_**
- The tag **shorthand** is a special type of alias that displays in situations where screen space is more valuable, notably with name disambiguation.
- **Aliases** are alternate names for a tag. These let you search for terms other than the exact tag name in order to find the tag again.
- **Parent Tags** are tags in which this tag can substitute for in searches. In other words, tags under this section are parents of this tag.
- Parent tags with the disambiguation check next to them will be used to help disambiguate tag names that may not be unique.
- For example: If you had a tag for "Freddy Fazbear", you might add "Five Nights at Freddy's" as one of the parent tags. If the disambiguation box is checked next to "Five Nights at Freddy's" parent tag, then the tag "Freddy Fazbear" will display as "Freddy Fazbear (Five Nights at Freddy's)". Furthermore, if the "Five Nights at Freddy's" tag has a shorthand like "FNAF", then the "Freddy Fazbear" tag will display as "Freddy Fazbear (FNAF)".
- The **color** option lets you select an optional color palette to use for your tag.
- The **"Is Category"** property lets you treat this tag as a category under which itself and any child tags inheriting from it will be sorted by inside the preview panel.
### Tag Manager