ci: use MkDocs for documentation site (#460)

* Use MkDocs for documentation

Using Material for MkDocs

* Enable edit buttons on pages

* Updates to mkdocs.yml

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -8,7 +8,7 @@ body:
       value: |
         *Please add an appropriate title for this issue.*
 
-        Before reporting, read the [documentation](https://github.com/TagStudioDev/TagStudio/blob/main/doc/index.md) and search existing [issues](https://github.com/TagStudioDev/TagStudio/issues).
+        Before reporting, read the [documentation](https://github.com/TagStudioDev/TagStudio/blob/main/docs/index.md) and search existing [issues](https://github.com/TagStudioDev/TagStudio/issues).
         Validate that you are using an up-to-date version[^1], your issue might already be fixed!
         Questions, guidance, and usage goes in [discussions](https://github.com/TagStudioDev/TagStudio/discussions). Invalid issues will be closed.
 
@@ -20,7 +20,7 @@ body:
       options:
         - label: I am using an up-to-date version.
           required: true
-        - label: I have read the [documentation](https://github.com/TagStudioDev/TagStudio/blob/main/doc/index.md).
+        - label: I have read the [documentation](https://github.com/TagStudioDev/TagStudio/blob/main/docs/index.md).
           required: true
         - label: I have searched existing [issues](https://github.com/TagStudioDev/TagStudio/issues).
           required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -8,7 +8,7 @@ body:
       value: |
         *Please add an appropriate title for this feature request.*
 
-        Before suggesting, read the [documentation](https://github.com/TagStudioDev/TagStudio/blob/main/doc/index.md) and search existing [issues](https://github.com/TagStudioDev/TagStudio/issues).
+        Before suggesting, read the [documentation](https://github.com/TagStudioDev/TagStudio/blob/main/docs/index.md) and search existing [issues](https://github.com/TagStudioDev/TagStudio/issues).
         Validate that you are using an up-to-date version[^1], your feature might already be implemented!
         Questions, guidance, and usage goes in [discussions](https://github.com/TagStudioDev/TagStudio/discussions). Invalid issues will be closed.
 
@@ -20,7 +20,7 @@ body:
       options:
         - label: I am using an up-to-date version.
           required: true
-        - label: I have read the [documentation](https://github.com/TagStudioDev/TagStudio/blob/main/doc/index.md).
+        - label: I have read the [documentation](https://github.com/TagStudioDev/TagStudio/blob/main/docs/index.md).
           required: true
         - label: I have searched existing [issues](https://github.com/TagStudioDev/TagStudio/issues).
           required: true

.github/workflows/publish_docs.yaml

@@ -0,0 +1,33 @@
+name: Publish Docs 
+
+on:
+  push:
+    branches:
+      - main 
+
+permissions:
+  contents: write
+
+concurrency: 
+  group: publish-docs
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+                  mkdocs-material-
+      - run: pip install mkdocs-material mkdocs-material[imaging]
+      - run: mkdocs gh-deploy --force
+
+

CONTRIBUTING.md

@@ -6,13 +6,13 @@ Thank you so much for showing interest in contributing to TagStudio! Here are a
 
 ## Getting Started
 
-- Check the [Planned Features](https://github.com/TagStudioDev/TagStudio/blob/main/doc/updates/planned_features.md) page, [FAQ](/README.md/#faq), as well as the open [Issues](https://github.com/TagStudioDev/TagStudio/issues) and [Pull Requests](https://github.com/TagStudioDev/TagStudio/pulls).
+- Check the [Planned Features](https://github.com/TagStudioDev/TagStudio/blob/main/docs/updates/planned_features.md) page, [FAQ](/README.md/#faq), as well as the open [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 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.
 
 ### Contribution Checklist
 
-- I've read the [Planned Features](https://github.com/TagStudioDev/TagStudio/blob/main/doc/updates/planned_features.md) page
+- I've read the [Planned Features](https://github.com/TagStudioDev/TagStudio/blob/main/docs/updates/planned_features.md) page
 - I've read the [FAQ](/README.md/#faq), including the "[Features I Likely Won't Add/Pull](/README.md/#features-i-likely-wont-addpull)" section
 - I've checked the open [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 _before_ starting work on it**, or have at least notified others in the relevant existing issue(s) of my intention to work on it

README.md

@@ -1,7 +1,7 @@
 # TagStudio (Alpha): A User-Focused Document Management System
 
 <p align="center">
-  <img width="60%" src="github_header.png">
+  <img width="60%" src="docs/assets/github_header.png">
 </p>
 
 > [!CAUTION]
@@ -11,7 +11,7 @@
 TagStudio is a photo & file organization application with an underlying system that focuses on giving freedom and flexibility to the user. No proprietary programs or formats, no sea of sidecar files, and no complete upheaval of your filesystem structure.
 
 <figure align="center">
-  <img width="80%" src="screenshot.jpg" alt="TagStudio Screenshot" align="center">
+  <img width="80%" src="docs/assets/screenshot.jpg" alt="TagStudio Screenshot" align="center">
 
   <figcaption><i>TagStudio Alpha v9.1.0 running on Windows 10.</i></figcaption>
 </figure>
@@ -53,7 +53,7 @@ TagStudio is a photo & file organization application with an underlying system t
 - Special search conditions for entries that are: `untagged`/`no tags` and `empty`/`no fields`.
 
 > [!NOTE]
-> For more information on the project itself, please see the [FAQ](#faq) section as well as the [documentation](/doc/index.md).
+> For more information on the project itself, please see the [FAQ](#faq) section as well as the [documentation](/docs/index.md).
 
 ## Contributing
 
@@ -178,7 +178,7 @@ As of writing (Alpha v9.3.0) the project is in a useable state, however it lacks
 ### What Features Are You Planning on Adding?
 
 > [!IMPORTANT]
-> See the [Planned Features](/doc/updates/planned_features.md) documentation for the latest feature lists. The lists here are currently being migrated over there with individual pages for larger features.
+> See the [Planned Features](/docs/updates/planned_features.md) documentation for the latest feature lists. The lists here are currently being migrated over there with individual pages for larger features.
 
 Of the several features I have planned for the project, these are broken up into “priority” features and “future” features. Priority features were originally intended for the first public release, however are currently absent from the Alpha v9.x.x builds.
 

doc/index.md

@@ -1,24 +0,0 @@
-# Welcome to the TagStudio Documentation!
-
-> [!WARNING]
-> This documentation is still a work in progress, and is intended to aide with deconstructing and understanding of the core mechanics of TagStudio and how it operates.
-
-<div align="center">
-	<img src="../github_header.png" alt="TagStudio Alpha" height="100">
-	<img src="https://i0.wp.com/www.bapl.org/wp-content/uploads/2019/02/old-under-construction-gif.gif" alt="Under Construction" height="100">
-</div>
-
-## Table of Contents
-
-- [Library](/doc/library/library.md)
-- [Entries](/doc/library/entry.md)
-- [Fields](/doc/library/field.md)
-- [Tags](/doc/library/tag.md)
-- [Tools & Macros](/doc/utilities/macro.md)
-- [Planned Features](/doc/updates/planned_features.md)
-
----
-
-### [Database Migration](/doc/updates/db_migration.md)
-
-The "Database Migration", "DB Migration", or "SQLite Migration" is an upcoming update to TagStudio which will replace the current JSON [library](/doc/library/library.md) with a SQL-based one, and will additionally include some fundamental changes to how some features such as [tags](/doc/library/tag.md) will work.

doc/library/library.md

@@ -1,11 +0,0 @@
-# Library
-
-The library is how TagStudio represents your chosen directory, with every file inside of it being displayed as an [entry](/doc/library/entry.md). You can have as many or few libraries as you wish, since each libraries' data is stored within a "`.TagStudio`" folder at its root.
-Note that this means [tags](/doc/library/tag.md) you create only exist _per-library_.
-
-### Library Contents
-
-- [Entries](/doc/library/entry.md)
-- [Fields](/doc/library/field.md)
-- [Tags](/doc/library/tag.md)
-- [Macros](/doc/utilities/macro.md)

doc/library/tag_categories.md

@@ -1,3 +0,0 @@
-# Tag Categories (Upcoming Feature)
-
-Replaces [Tag Fields](/doc/library/field.md#tag_box). Tags are able to be marked as a “category” which then displays as tag fields currently do, with any tags inheriting from that category being displayed underneath.

doc/library/tag_overrides.md

@@ -1,16 +0,0 @@
-# Tag Overrides (Upcoming Feature)
-
-Tag overrides are the ability to add or remove [parent tags](/doc/library/tag.md#subtags) from a [tag](/doc/library/tag.md) on a per- [entry](/doc/library/entry.md) basis. Relies on the [Database Migration](/doc/updates/db_migration.md) update being complete.
-
-## Examples
-
-<figure>
-  <img src="../assets/tag_override_ex-1.png" alt="Example 1" height="300">
-  <figcaption>Ex. 1 - Comparing standard tag composition vs additive and subtractive inheritance overrides.</figcaption>
-</figure>
-
-<figure>
-  <img src="../assets/tag_override_ex-2.png" alt="Example 2" height="300">
-
-  <figcaption>Ex. 2 - Parent tag swap using tag overrides.</figcaption>
-</figure>

doc/updates/planned_features.md

@@ -1,59 +0,0 @@
-# Planned Features
-
-The following lists outline the planned major and minor features for TagStudio, in no particular order.
-
-# Major Features
-
-- [SQL Database Migration](/doc/updates/db_migration.md)
-- Multiple Directory Support
-- [Tags Categories](/doc/library/tag_categories.md)
-- [Entry Groups](/doc/library/entry_groups.md)
-- [Tag Overrides](/doc/library/tag_overrides.md)
-- Tagging Panel
-  - Top Tags
-  - Recent Tags
-  - Tag Search
-  - Pinned Tags
-- Configurable Default Fields (May be part of [Macros](/doc/utilities/macro.md))
-- Deep File Extension Control
-- Settings Menu
-- Custom User Colors
-- Search Engine Rework
-  - Boolean Search
-  - Tag Objects In Search
-  - Search For Fields
-  - Sortable Search Results
-- Automatic Entry Relinking
-  - Detect Renames
-  - Detect Moves
-- Thumbnail Caching
-- User-Defined Fields
-- Exportable Library/Tag Data
-  - Exportable Human-Readable Library
-  - Exportable/Importable Human-Readable “Tag Packs”
-  - Exportable/Importable Color Palettes
-- Configurable Thumbnail Labels
-  - Toggle Extension Label
-  - Toggle File Size Label
-- Configurable Thumbnail Tag Badges
-  - Customize tags that appear instead of just “Archive” and “Favorite”
-- OCR Search
-
-## Minor Features
-
-- Deleting Tags
-- Merging Tags
-- Tag Icons
-- Tag/Field Copy + Paste
-- Collage UI
-- Resizable Thumbnail Grid
-- Draggable Files Outside The Program
-- File Property Caching
-- 3D Previews
-- Audio Waveform Previews
-  - Toggle Between Waveform And Album Artwork
-- PDF Previews
-- SVG Previews
-- Full Video Player
-- Duration Properties For Video + Audio Files
-- Optional Starter Tag Packs

doc/utilities/macro.md

@@ -1,43 +0,0 @@
-# Tools & Macros
-
-Tools and macros are features that serve to create a more fluid [library](/doc/library/library.md)-managing process, or provide some extra functionality. Please note that some are still in active development and will be fleshed out in future updates.
-
-## Tools
-
-### Fix Unlinked Entries
-
-This tool displays the number of unlinked [entries](/doc/library/entry.md), and some options for their resolution.
-
-1. Refresh
-   - Scans through the library and updates the unlinked entry count.
-2. Search & Relink
-   - Attempts to automatically find and reassign missing files.
-3. Delete Unlinked Entries
-   - Displays a confirmation prompt containing the list of all missing files to be deleted before committing to or cancelling the operation.
-
-### Fix Duplicate Files
-
-This tool allows for management of duplicate files in the library using a [DupeGuru](https://dupeguru.voltaicideas.net/) file.
-
-1. Load DupeGuru File
-   - load the "results" file created from a DupeGuru scan
-2. Mirror Entries
-   - Duplicate entries will have their contents mirrored across all instances. This allows for duplicate files to then be deleted with DupeGuru as desired, without losing the [field](/doc/library/field.md) data that has been assigned to either. (Once deleted, the "Fix Unlinked Entries" tool can be used to clean up the duplicates)
-
-### Create Collage
-
-This tool is a preview of an upcoming feature. When selected, TagStudio will generate a collage of all the contents in a Library, which can be found in the Library folder ("/your-folder/.TagStudio/collages/"). Note that this feature is still in early development, and doesn't yet offer any customization options.
-
-## Macros
-
-### Auto-fill [WIP]
-
-Tool is in development and will be documented in future update.
-
-### Sort fields
-
-Tool is in development, will allow for user-defined sorting of [fields](/doc/library/field.md).
-
-### Folders to Tags
-
-Creates tags from the existing folder structure in the library, which are previewed in a hierarchy view for the user to confirm. A tag will be created for each folder and applied to all entries, with each subfolder being linked to the parent folder as a [parent tag](/doc/library/tag.md#subtags). Tags will initially be named after the folders, but can be fully edited and customized afterwards.

docs/index.md

@@ -0,0 +1,50 @@
+---
+title: Home
+---
+
+# Welcome to the TagStudio Documentation!
+
+!!! warning
+	This documentation is still a work in progress, and is intended to aide with deconstructing and understanding of the core mechanics of TagStudio and how it operates.
+
+![TagStudio Alpha](assets/github_header.png)
+
+
+TagStudio is a photo & file organization application with an underlying system that focuses on giving freedom and flexibility to the user. No proprietary programs or formats, no sea of sidecar files, and no complete upheaval of your filesystem structure.
+
+<figure markdown="span">
+  ![TagStudio screenshot](assets/screenshot.jpg)
+  <figcaption>TagStudio Alpha v9.1.0 running on Windows 10</figcaption>
+</figure>
+
+## Goals
+
+- To achieve a portable, privacy-oriented, open, extensible, and feature-rich system of organizing and rediscovering files.
+- To provide powerful methods for organization, notably the concept of tag composition, or “taggable tags”.
+- To create an implementation of such a system that is resilient against a user’s actions outside the program (modifying, moving, or renaming files) while also not burdening the user with mandatory sidecar files or otherwise requiring them to change their existing file structures and workflows.
+- To support a wide range of users spanning across different platforms, multi-user setups, and those with large (several terabyte) libraries.
+- To make the darn thing look like nice, too. It’s 2024, not 1994.
+
+## Priorities
+
+1. **The concept.** Even if TagStudio as a project or application fails, I’d hope that the idea lives on in a superior project. The [goals](#goals) outlined above don’t reference TagStudio once - _TagStudio_ is what references the _goals._
+2. **The system.** Frontends and implementations can vary, as they should. The core underlying metadata management system is what should be interoperable between different frontends, programs, and operating systems. A standard implementation for this should settle as development continues. This opens up the doors for improved and varied clients, integration with third-party applications, and more.
+3. **The application.** If nothing else, TagStudio the application serves as the first (and so far only) implementation for this system of metadata management. This has the responsibility of doing the idea justice and showing just what’s possible when it comes to user file management.
+4. (The name.) I think it’s fine for an app or client, but it doesn’t really make sense for a system or standard. I suppose this will evolve with time.
+
+## Current Features
+
+- Create libraries/vaults centered around a system directory. Libraries contain a series of entries: the representations of your files combined with metadata fields. Each entry represents a file in your library’s directory, and is linked to its location.
+- Add metadata to your library entries, including:
+	- Name, Author, Artist (Single-Line Text Fields)
+	- Description, Notes (Multiline Text Fields)
+	- Tags, Meta Tags, Content Tags (Tag Boxes)
+- Create rich tags composed of a name, a list of aliases, and a list of “subtags” - being tags in which these tags inherit values from.
+- Search for entries based on tags, ~~metadata~~ (TBA), or filenames/filetypes (using `filename: <query>`)
+- Special search conditions for entries that are: `untagged`/`no tags` and `empty`/`no fields`.
+
+## Important Updates
+
+### [Database Migration](updates/db_migration.md)
+
+The "Database Migration", "DB Migration", or "SQLite Migration" is an upcoming update to TagStudio which will replace the current JSON [library](library/index.md) with a SQL-based one, and will additionally include some fundamental changes to how some features such as [tags](library/tag.md) will work.

docs/install.md

@@ -0,0 +1,18 @@
+# Installation
+
+To download TagStudio, visit the [Releases](https://github.com/TagStudioDev/TagStudio/releases) section of the GitHub repository and download the latest release for your system under the "Assets" section. TagStudio is available for **Windows**, **macOS** _(Apple Silicon & Intel)_, and **Linux**. Windows and Linux builds are also available in portable versions if you want a more self-contained executable to move around.
+
+For video thumbnails and playback, you'll also need [FFmpeg](https://ffmpeg.org/download.html) installed on your system. 
+
+!!! info "For macOS Users"
+    On macOS, you may be met with a message saying _""TagStudio" can't be opened because Apple cannot check it for malicious software."_ 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 _""TagStudio" was blocked from use because it is not from an identified developer."_ Click the "Open Anyway" button to allow TagStudio to run. You should only have to do this once after downloading the application.
+
+## Optional Arguments
+
+Optional arguments to pass to the program:
+
+`--open <path>` / `-o <path>`
+: Path to a TagStudio Library folder to open on start.
+
+`--config-file <path>` / `-c <path>`
+: Path to the TagStudio config file to load.

docs/library/entry.md

@@ -1,25 +1,26 @@
 # Entry
 
-Entries are the units that fill a [library](/doc/library/library.md). Each one corresponds to a file, holding a reference to it along with the metadata associated with it.
+Entries are the units that fill a [library](index.md). Each one corresponds to a file, holding a reference to it along with the metadata associated with it.
 
 ### Entry Object Structure
 
-1. `id`:
-   - Int, Unique, **Required**
-   - The ID for the Entry.
-   - Used for internal processing
+1. `id`
+      - Int, Unique, **Required**
+      - The ID for the Entry.
+      - Used for internal processing
 2. `filename`:
-   - String, **Required**
-   - The filename with extension of the referenced media file.
+      - String, **Required**
+      - The filename with extension of the referenced media file.
 3. `path`:
-   - String, **Required**, OS Agnostic
-   - The folder path in which the media file is located in.
-4. [`fields`](/doc/library/field.md):
-   - List of dicts, Optional
-   - A list of Field ID/Value dicts.
+      - String, **Required**, OS Agnostic
+      - The folder path in which the media file is located in.
+4. [`fields`](field.md):
+      - List of dicts, Optional
+      - A list of Field ID/Value dicts.
 
-NOTE: _Entries currently have several unused optional fields intended for later features._
+!!! note
+      Entries currently have several unused optional fields intended for later features.
 
-## Retrieving Entries based on [Tag](/doc/library/tag.md) Cluster
+## Retrieving Entries based on [Tag](tag.md) Cluster
 
 By default when querying Entries, each Entry's `tags` list (stored in the form of Tag `id`s) is compared against the Tag `id`s in a given Tag cluster (list of Tag `id`s) or appended clusters in the case of multi-term queries. The type of comparison depends on the type of query and whether or not it is an inclusive or exclusive query, or a combination of both. This default searching behavior is done in _O(n)_ time, but can be sped up in the future by building indexes on certain search terms. These indexes can be stored on disk and loaded back into memory in future sessions. These indexes will also need to be updated as new Tags and Entries are added or edited.

docs/library/entry_groups.md

@@ -1,3 +1,8 @@
-# Entry Groups (Upcoming Feature)
+---
+tags:
+  - Upcoming Feature
+---
+
+# Entry Groups
 
 Entries can be grouped via tags marked as “groups” which when applied to different entries will signal TagStudio to treat those entries as a single group inside of searches and browsing.

docs/library/field.md

@@ -1,6 +1,6 @@
 # Field
 
-Fields are the building blocks of metadata stored in [entries](/doc/library/entry.md). Fields have several base types for representing different kinds of information, including:
+Fields are the building blocks of metadata stored in [entries](entry.md). Fields have several base types for representing different kinds of information, including:
 
 #### `text_line`
 
@@ -14,7 +14,7 @@ Fields are the building blocks of metadata stored in [entries](/doc/library/entr
 
 #### `tag_box`
 
-- A box of [tags](/doc/library/tag.md) defined and added by the user.
+- A box of [tags](tag.md) defined and added by the user.
 - Multiple tag boxes can be used to separate classifications of tags.
   - e.g: Content Tags, Meta Tags, etc.
 
@@ -31,4 +31,4 @@ Fields are the building blocks of metadata stored in [entries](/doc/library/entr
 
 #### `collation` [obsolete]
 
-- Previously used for associating files to be used in a [collation](/doc/utilities/macro.md#create-collage), will be removed in favor of a more flexible feature in future updates.
+- Previously used for associating files to be used in a [collation](../utilities/macro.md#create-collage), will be removed in favor of a more flexible feature in future updates.

docs/library/index.md

@@ -0,0 +1,4 @@
+# Library
+
+The library is how TagStudio represents your chosen directory, with every file inside of it being displayed as an [entry](entry.md). You can have as many or few libraries as you wish, since each libraries' data is stored within a `.TagStudio` folder at its root.
+Note that this means [tags](tag.md) you create only exist _per-library_.

docs/library/tag.md

@@ -1,20 +1,20 @@
 # Tag
 
-Tags are user-defined attributes made up of one or more keywords, aliases, and relationships to other tags. A person, place, thing, concept, you name it! Tags allow for a more sophisticated way to organize and search [entries](/doc/library/entry.md) thanks to their aliases, parent tags, and more.
+Tags are user-defined attributes made up of one or more keywords, aliases, and relationships to other tags. A person, place, thing, concept, you name it! Tags allow for a more sophisticated way to organize and search [entries](entry.md) thanks to their aliases, parent tags, and more.
 Tags can be as simple or complex as wanted, so that any user can tune TagStudio to fit their needs.
 
-Among the things that make tags so useful, aliases give the ability to contain alternate names and spellings, making searches intuitive and expansive. Furthermore, parent-tags/subtags offer relational organization capabilities for the structuring and connection of the [library's](/doc/library/library.md) contents.
+Among the things that make tags so useful, aliases give the ability to contain alternate names and spellings, making searches intuitive and expansive. Furthermore, parent-tags/subtags offer relational organization capabilities for the structuring and connection of the [library's](index.md) contents.
 
 ## Tag Object Structure
 
-#### `id`
+### `id`
 
 ID for the tag.
 
 - Int, Unique, Required
 - Used for internal processing
 
-#### `name`
+### `name`
 
 The normal name of the tag, with no shortening or specification.
 
@@ -22,7 +22,7 @@ The normal name of the tag, with no shortening or specification.
 - Doesn't have to be unique
 - Used for display, searching, and storing
 
-#### `shorthand`
+### `shorthand`
 
 The shorthand name for the tag. Works like an alias but is used for specific display purposes.
 
@@ -30,7 +30,7 @@ The shorthand name for the tag. Works like an alias but is used for specific dis
 - Doesn't have to be unique
 - Used for display and searching
 
-#### `aliases`
+### `aliases`
 
 Alternate names for the tag.
 
@@ -38,14 +38,14 @@ Alternate names for the tag.
 - Recommended to be unique to this tag
 - Used for searching
 
-#### `subtags`
+### `subtags`
 
 Other Tags that make up properties of this tag. Also called "parent tags".
 
 - List of Strings, Optional
 - Used for display (first parent tag only) and searching.
 
-#### `color`
+### `color`
 
 A color name string for customizing the tag's display color
 

docs/library/tag_categories.md

@@ -0,0 +1,8 @@
+---
+tags:
+  - Upcoming Feature
+---
+
+# Tag Categories
+
+Replaces [Tag Fields](field.md#tag_box). Tags are able to be marked as a “category” which then displays as tag fields currently do, with any tags inheriting from that category being displayed underneath.

docs/library/tag_overrides.md

@@ -0,0 +1,20 @@
+---
+tags:
+  - Upcoming Feature
+---
+
+# Tag Overrides
+
+Tag overrides are the ability to add or remove [parent tags](tag.md#subtags) from a [tag](tag.md) on a per- [entry](entry.md) basis. Relies on the [Database Migration](../updates/db_migration.md) update being complete.
+
+## Examples
+
+<figure markdown="span">
+  ![Example 1](../assets/tag_override_ex-1.png){ height="300" }
+  <figcaption>Ex. 1 - Comparing standard tag composition vs additive and subtractive inheritance overrides.</figcaption>
+</figure>
+
+<figure markdown="span">
+  ![Example 2](../assets/tag_override_ex-2.png){ height="300" }
+  <figcaption>Ex. 2 - Parent tag swap using tag overrides.</figcaption>
+</figure>

docs/updates/changelog.md

@@ -0,0 +1,4 @@
+---
+title: Changelog
+---
+--8<-- "CHANGELOG.md"

docs/updates/db_migration.md

@@ -1,10 +1,10 @@
 # Database Migration
 
-The database migration is an upcoming refactor to TagStudio's library data storage system. The database will be migrated from a JSON-based one to a SQLite-based one. Part of this migration will include a reworked schema, which will allow for several new features and changes to how [tags](/doc/library/tag.md) and [fields](/doc/library/field.md) operate.
+The database migration is an upcoming refactor to TagStudio's library data storage system. The database will be migrated from a JSON-based one to a SQLite-based one. Part of this migration will include a reworked schema, which will allow for several new features and changes to how [tags](../library/tag.md) and [fields](../library/field.md) operate.
 
 ## Schema
 
-<img src="../assets/db_schema.png" alt="Database Schema" width="500">
+![Database Schema](../assets/db_schema.png){ width="600" }
 
 ### `alias` Table
 
@@ -37,7 +37,7 @@ _Description TBA_
 ## Resulting New Features and Changes
 
 - Multiple Directory Support
-- [Tag Categories](/doc/library/tag_categories.md) (Replaces [Tag Fields](/doc/library/field.md#tag_box))
-- [Tag Overrides](/doc/library/tag_overrides.md)
-- User-Defined [Fields](/doc/library/field.md)
+- [Tag Categories](../library/tag_categories.md) (Replaces [Tag Fields](../library/field.md#tag_box))
+- [Tag Overrides](../library/tag_overrides.md)
+- User-Defined [Fields](../library/field.md)
 - Tag Icons

docs/updates/planned_features.md

@@ -0,0 +1,59 @@
+# Planned Features
+
+The following lists outline the planned major and minor features for TagStudio, in no particular order.
+
+# Major Features
+
+- [ ] [SQL Database Migration](../updates/db_migration.md)
+- [ ] Multiple Directory Support
+- [ ] [Tags Categories](../library/tag_categories.md)
+- [ ] [Entry Groups](../library/entry_groups.md)
+- [ ] [Tag Overrides](../library/tag_overrides.md)
+- [ ] Tagging Panel
+    - [ ] Top Tags
+    - [ ] Recent Tags
+    - [ ] Tag Search
+    - [ ] Pinned Tags
+- [ ] Configurable Default Fields (May be part of [Macros](../utilities/macro.md))
+- [ ] Deep File Extension Control
+- [ ] Settings Menu
+- [ ] Custom User Colors
+- [ ] Search Engine Rework
+    - [ ] Boolean Search
+    - [ ] Tag Objects In Search
+    - [ ] Search For Fields
+    - [ ] Sortable Search Results
+- [ ] Automatic Entry Relinking
+    - [ ] Detect Renames
+    - [ ] Detect Moves
+- [ ] Thumbnail Caching
+- [ ] User-Defined Fields
+- [ ] Exportable Library/Tag Data
+    - [ ] Exportable Human-Readable Library
+    - [ ] Exportable/Importable Human-Readable “Tag Packs”
+    - [ ] Exportable/Importable Color Palettes
+- [ ] Configurable Thumbnail Labels
+    - [ ] Toggle Extension Label
+    - [ ] Toggle File Size Label
+- [ ] Configurable Thumbnail Tag Badges
+    - [ ] Customize tags that appear instead of just “Archive” and “Favorite”
+- [ ] OCR Search
+
+## Minor Features
+
+- [ ] Deleting Tags
+- [ ] Merging Tags
+- [ ] Tag Icons
+- [ ] Tag/Field Copy + Paste
+- [ ] Collage UI
+- [ ] Resizable Thumbnail Grid
+- [ ] Draggable Files Outside The Program
+- [ ] File Property Caching
+- [ ] 3D Previews
+- [ ] Audio Waveform Previews
+    - [ ] Toggle Between Waveform And Album Artwork
+- [ ] PDF Previews
+- [ ] SVG Previews
+- [ ] Full Video Player
+- [ ] Duration Properties For Video + Audio Files
+- [ ] Optional Starter Tag Packs

docs/usage.md

@@ -0,0 +1,86 @@
+# Usage
+
+## Creating/Opening a Library
+
+With TagStudio opened, start by creating a new library or opening an existing one using File -> Open/Create Library from the menu bar. TagStudio will automatically create a new library from the chosen directory if one does not already exist. Upon creating a new library, TagStudio will automatically scan your folders for files and add those to your library (no files are moved during this process!).
+
+## Refreshing the Library
+
+In order to scan for new files or file changes, you’ll need to manually go to File -> Refresh Directories.
+
+!!! note
+    In the future, library refreshing will also be automatically done in the background, or additionally on app startup.
+
+## Adding Metadata to Entries
+
+To add a metadata field to a file entry, start by clicking the “Add Field” button under the file preview in the right-hand preview panel. From the dropdown menu, select the type of metadata field you’d like to add to the entry.
+
+## Editing Metadata Fields
+
+### Text Line / Text Box
+
+Hover over the field and click the pencil icon. From there, add or edit text in the dialog box popup.
+
+### Tag Box
+
+Click the “+” button at the end of the Tags list, and search for tags to add inside the new dialog popup. Click the “+” button next to whichever tags you want to add. Alternatively, after you search for a tag, press the Enter/Return key to add the add the first item in the list. Press Enter/Return once more to close the dialog box
+
+!!! warning
+    Keyboard control and navigation is currently _very_ buggy, but will be improved in future versions.
+
+## Creating Tags
+
+To create a new tag, click on Edit -> New Tag from the menu bar. From there, enter a tag name, shorthand name, any tag aliases separated by newlines, any subtags, and an optional color.
+
+- The tag **shorthand** is a type of alias that displays in situations when screen space is more valuable (ex. as a subtag for other tags).
+- **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.
+- **Subtags** are tags in which this tag is a child tag of. In other words, tags under this section are parents of this tag. For example, if you had a tag for a character from a show, you would make the show a subtag of this character. This would display as “Character (Show)” in most areas of the app. The first tag in this list is used as the tag shown in parentheses for specification.
+- The **color** dropdown lets you select an optional color for this tag to display as.
+
+## Editing Tags
+
+To edit a tag, right-click the tag in the tag field of the preview pane and select “Edit Tag”
+
+## Relinking Renamed/Moved Files
+
+Inevitably, some of the files inside your library will be renamed, moved, or deleted. If a file has been renamed or moved, TagStudio will display the thumbnail as a red tag with a cross through it _(this icon is also used for items with broken thumbnails)._ To relink moved files or delete these entries, go to Tools -> Manage Unlinked Entries. Click the “Refresh” button to scan your library for unlinked entries. Once complete, you can attempt to “Search & Relink” any unlinked entries to their respective files, or “Delete Unlinked Entries” in the event the original files have been deleted and you no longer wish to keep their metadata entries inside your library.
+
+!!! warning
+    There is currently no method to relink entries to files that have been renamed - only moved or deleted. This is a top priority for future releases.
+
+!!! warning
+    If multiple matches for a moved file are found (matches are currently defined as files with a matching filename as the original), TagStudio will currently ignore the match groups. Adding a GUI for manual selection, as well as smarter automated relinking, are top priorities for future versions.
+
+## Saving the Library
+
+Libraries are saved upon exiting the program. To manually save, select File -> Save Library from the menu bar. To save a backup of your library, select File -> Save Library Backup from the menu bar.
+
+## Half-Implemented Features
+
+### Fix Duplicate Files
+
+Load in a .dupeguru file generated by [dupeGuru](https://github.com/arsenetar/dupeguru/) and mirror metadata across entries marked as duplicates. After mirroring, return to dupeGuru to manage deletion of the duplicate files. After deletion, use the “Fix Unlinked Entries” feature in TagStudio to delete the duplicate set of entries for the now-deleted files
+
+!!! danger "Caution"
+    While this feature is functional, it’s a pretty roundabout process and can be streamlined in the future.
+
+### Image Collage
+
+Create an image collage of your photos and videos.
+
+!!! danger "Caution"
+    Collage sizes and options are hardcoded, and there's no GUI indicating the process of the collage creation.
+
+### Macros
+
+Apply tags and other metadata automatically depending on certain criteria. Set specific macros to run when the files are added to the library. Part of this includes applying tags automatically based on parent folders.
+
+!!! danger "Caution"
+    Macro options are hardcoded, and there’s currently no way for the user to interface with this (still incomplete) system at all.
+
+### Gallery-dl Sidecar Importing
+
+Import JSON sidecar data generated by [gallery-dl](https://github.com/mikf/gallery-dl).
+
+!!! danger "Caution"
+    This feature is not supported or documented in any official capacity whatsoever. It will likely be rolled-in to a larger and more generalized sidecar importing feature in the future.

docs/utilities/macro.md

@@ -0,0 +1,46 @@
+# Tools & Macros
+
+Tools and macros are features that serve to create a more fluid [library](../library/index.md)-managing process, or provide some extra functionality. Please note that some are still in active development and will be fleshed out in future updates.
+
+## Tools
+
+### Fix Unlinked Entries
+
+This tool displays the number of unlinked [entries](../library/entry.md), and some options for their resolution.
+
+Refresh
+: Scans through the library and updates the unlinked entry count.
+
+Search & Relink
+: Attempts to automatically find and reassign missing files.
+
+Delete Unlinked Entries
+: Displays a confirmation prompt containing the list of all missing files to be deleted before committing to or cancelling the operation.
+
+### Fix Duplicate Files
+
+This tool allows for management of duplicate files in the library using a [DupeGuru](https://dupeguru.voltaicideas.net/) file.
+
+Load DupeGuru File
+: load the "results" file created from a DupeGuru scan
+
+Mirror Entries
+: Duplicate entries will have their contents mirrored across all instances. This allows for duplicate files to then be deleted with DupeGuru as desired, without losing the [field](../library/field.md) data that has been assigned to either. (Once deleted, the "Fix Unlinked Entries" tool can be used to clean up the duplicates)
+
+### Create Collage
+
+This tool is a preview of an upcoming feature. When selected, TagStudio will generate a collage of all the contents in a Library, which can be found in the Library folder ("/your-folder/.TagStudio/collages/"). Note that this feature is still in early development, and doesn't yet offer any customization options.
+
+## Macros
+
+### Auto-fill [WIP]
+
+Tool is in development and will be documented in future update.
+
+### Sort fields
+
+Tool is in development, will allow for user-defined sorting of [fields](../library/field.md).
+
+### Folders to Tags
+
+Creates tags from the existing folder structure in the library, which are previewed in a hierarchy view for the user to confirm. A tag will be created for each folder and applied to all entries, with each subfolder being linked to the parent folder as a [parent tag](../library/tag.md#subtags). Tags will initially be named after the folders, but can be fully edited and customized afterwards.

mkdocs.yml

@@ -0,0 +1,137 @@
+# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+
+# MkDocs: https://www.mkdocs.org/
+# Material for MkDocs: https://squidfunk.github.io/mkdocs-material/
+
+# To install:
+# pip install mkdocs-material
+
+# To run the preview server:
+# mkdocs serve
+
+site_name: TagStudio
+site_description: "A User-Focused Photo & File Management System"
+site_url: https://tagstudiodev.github.io/tagstudio
+repo_url: https://github.com/TagStudioDev/TagStudio
+repo_name: TagStudioDev/TagStudio
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/TagStudioDev
+    - icon: fontawesome/brands/discord
+      link: https://discord.gg/hRNnVKhF2G
+  tags:
+    Upcoming Feature: upcoming
+
+# by default the navigation is an alphanumerically sorted, 
+# nested list of all the Markdown files found within the /docs directory
+# where index files are always first
+# uncomment the following to configure the navigation manually:
+
+# nav:
+#   - Home:
+#     - index.md
+#     - install.md
+#     - usage.md
+#   - Library:
+#     - library/index.md
+#     - library/entry.md
+#     - library/entry_groups.md
+#     - library/field.md
+#     - library/tag.md
+#     - library/tag_categories.md
+#     - library/tag_overrides.md
+#   - Utilities:
+#     - utilities/macro.md
+#   - Updates:
+#     - updates/changelog.md
+#     - updates/planned_features.md
+#     - updates/db_migration.md
+
+theme:
+  name: material
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)" 
+      scheme: default
+      primary: deep purple
+      accent: deep purple
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)" 
+      scheme: slate
+      primary: deep purple
+      accent: deep purple
+      toggle:
+        icon: material/brightness-4
+        name: SSwitch to system preference
+  logo: assets/icon.png
+  favicon: assets/icon.ico
+  font: false # use system fonts
+  language: en
+  features:
+    - navigation.instant
+    - navigation.indexes
+    - navigation.tracking
+    - navigation.expand
+    - navigation.sections
+    #- navigation.tabs
+    #- content.tabs.link
+    #- navigation.top
+    - search.suggest
+    - content.code.annotate
+    - content.action.edit
+  icon:
+    repo: fontawesome/brands/github
+    tag:
+      upcoming: material/flask-outline
+
+markdown_extensions:
+
+  # Python Markdown
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - toc:
+      permalink: true
+
+  # Python Markdown Extensions
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+  - pymdownx.snippets
+
+plugins:
+  - search
+  - tags
+  - social # social embed cards
+      enabled: !ENV [CI, false] # enabled only when running in CI (eg GitHub Actions)