# TagSpaces Documentation
> Complete reference documentation for TagSpaces
This file contains all documentation content in a single document following the llmstxt.org standard.
## About the docs
# About this documentation
This documentation is work in progress, the articles are being updated on a regular base.
## Documentation structure
This documentation is built using [Docusaurus](https://docusaurus.io/), for a streamlined and simple user experience. Each **page** will concern a particular topic, giving **detailed and illustrated explanations** and **instructions** about it. Every page is broken down to different level headings.
The navigation sidebar on the left side of this page will represent the **chapters** as expandable topics, with the **sections** listed in each expanded view.
## Illustrations
For preparing the screenshots for this documentation we use shapes from the following SVG file.
We used another great open source product called [Inkscape](https://inkscape.org/) for the creation of the graphics.
The color of the shapes has the following HEX encoding: `#ef2dae`
## Text markup
You will notice, that certain words are marked with **bold text**. These either mean names of elements, or significant notes/concepts about usage. _Italicized words_ usually mark menu items, or other selectable elements, although it is not a hard and fast rule.
Bulleted lists will be used to
- Improve **readability**
- Make it **easier to find** what you are looking for.
## Document symbols
There are currently two types of symbols, apart from the usual text formatting and annotations, that you can find on these pages:
- - means that the described feature is part of the TagSpaces Pro and Custom editions.
- ⚒ - means that the section is not ready yet and may contain unclear, or not up-to-date information, or sections might be missing entirely.
## Contribution
This documentation project is hosted on [GitHub](https://github.com/tagspaces/documentation), and uses the [Docusaurus MD format](https://docusaurus.io/). Enhancement, or corrections are welcome via pull requests. For the markdown syntax used for the document please refer to the [Style Guide](/markdown)
## Credits
**Original text and images** in this documentation were **created and edited by**:
- [**Ilian Sapundshiev**](https://www.ilian.me) - initiator of the TagSpaces project
- [**Attila Orosz**](https://www.linkedin.com/in/attila-orosz-43832114) - main editor of the documentation for version 2 of the product, he can be reached via [email](mailto:attila.orosz@mail.com).
Articles published on the [TagSpaces Blog](https://www.tagspaces.org/blog/), served as the **basis upon which this documentation was built**. Fragments of the original text can still be found in the documentation, without marking the original author.
## License of the documentation
TagSpaces Documentation by TagSpaces Authors is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.Based on a work at https://github.com/tagspaces/documentation.
---
## AI Functionality
Starting with version 6.1, TagSpaces can connect to [Ollama](https://ollama.com/) as an external AI service provider. Ollama is a **locally installed offline** software that enables running AI models (LLMs - large language models) directly on your computer.
:::tip
TagSpaces does not have its own AI engine or models but relies entirely on external AI software like Ollama for these features. **All AI features are disabled by default**.
:::
## Prerequisites
- A modern PC with a recent Nvidia/AMD graphics card or a Mac with an Apple Silicon processor. Ollama also works on regular CPUs, but performance may be slower.
- [Download](https://ollama.com/download) and install the Ollama software.
- At least 10 GB of free hard drive space for LLMs.
## AI Configuration
In the settings, a new tab called **AI** is available. Here, you can add AI engines and manage their models.
### Adding an AI Engine
After installing Ollama, you can add it by clicking the **Add AI Engine** button in TagSpaces.
If everything is set up correctly, you'll see a new section labeled "Ollama" with a green indicator, meaning Ollama is running in the background. If there are connection issues, the indicator will turn red.
By default, the configuration assumes the Ollama service is running on your local machine `https://localhost:11434`. However, it can also run on other computers in your network. You can add multiple Ollama configurations using the **Add AI Engine** button. Select the desired engine in the **Default AI Engine** dropdown.
### Downloading Models
The next step is to download a suitable model (LLM). This can be done via the **Default model for text-based tasks** dropdown.
In the "Example installable AI models" section, you can choose a suitable model. For text-based tasks, we suggest the **llama3.2** model. For image-based tasks (e.g., image description), you can use *llava* or *llama3.2-vision*. While *llama3.2-vision* delivers better results, it is significantly slower.
Once you select a model, a progress dialog will show the download status. Note that models are typically several gigabytes in size, so patience is required.
If you can't find the desired model, you can install additional ones using Ollama's [command-line tool](https://github.com/ollama/ollama/tree/main?tab=readme-ov-file#cli-reference).
## AI Chat in Folders
If configured correctly, a new button will appear next to the perspective switcher in the folder area. Clicking it opens the **AI Chat** tab in the folder properties.
At the top of the tab, select the model for the AI chat. At the bottom, use the AI prompt to ask questions.
You can maintain a separate chat for each folder, enabling chat-based research or project organization directly in folders.
:::warning
All chat history, including dropped images, is saved in the **ai** folder within the **.ts** subfolder of the current folder. Deleting the **ai** folder or the current folder will delete the chat history.
:::
## AI Features for Files
AI-related file features are part of the PRO version. These functionalities are currently available:
- **Generate image descriptions** for JPG and PNG files.
- **Generate tags** from image descriptions.
- **Generate tags** for images in JPG and PNG formats.
- **Generate PDF descriptions** based on content.
- **Summarization** of text based files like HTML, TXT and MarkDown
- **Batch AI-processing** of multiple files
- Extraction of **dominant colors** in images
- **Language configuration** for generated content
## Custom prompts for the AI features
In the bottom of the AI tab, there is a section called _Advanced_ which is closed by default. When you open it, you will find text areas where the prompts for the AI/LLM features can be adjusted.
## Upcoming AI Features
The following features are on the development roadmap for TagSpaces.
- Integration with additional AI engines
- Translation of generated content
Any **feedback and new ideas** are welcomed in our [**forum**](https://tagspaces.discourse.group/c/feature-requests/6).
---
## Annotating files and folders
This pages was moved in the following pages:
- [File annotations](/files)
- [Folder annotations](/folders)
---
## Bookmarks
# Bookmark to files and folders
In the PRO versions you can add any file or folder as bookmark for an easy later access.
The **Bookmarks Area (1)** are accessible from the **Quick Access (2)** section as seen in the next screenshot.
The adding or removing of a bookmark can be done with button marked with **(3)** in the previous screenshot.
:::info
Bookmark reside only in you current installation of the application, as for now they can not be transferred or shared with anybody.
:::
In the context menu **(4)** of the bookmarks you have the following options:
- **Refresh** - will reload the bookmarks from the application memory
- **Delete all Bookmarks** - will irreversible delete all your bookmarks
---
## Perspectives Overview
When you navigate to a folder in your active location, the files contained in the selected folder will be displayed in the main file browsing area of the user interface. TagSpaces offers flexible views to display your files. We call these views **perspectives**.
Perspectives are modular extensions that allow more flexibility, easier development, and customizability. TagSpaces is delivered by default with two perspective, while additional perspectives can be found in the PRO products. This is a list of all currently available :
- [Grid Perspective](/perspectives/grid/) - Presents files and folders in a grid format, suitable for tagging and file management. It is the **default** perspective built into TagSpaces.
- [List Perspective](/perspectives/list/) - Presents files in a list format, suitable for tagging and file management.
- [Gallery Perspective](/perspectives/gallery/) - Optimized for browsing and viewing images and photos.
- [Mapique Perspective](/perspectives/mapique/) - Displays geo-tagged files and folders on a map. Available in the Pro edition.
- [Kanban Perspective](/perspectives/kanban/) - Shows your files as tasks on a Kanban board, representing subfolders as columns on the board.
- [FolderViz Perspective](/perspectives/folderviz/) - An experimental perspective that applies information visualization concepts to presenting your folder and file structures.
## Switching Perspectives
The perspective for the current folder can be switched in two ways. The easiest method is to use the perspective switch located in the bottom-right corner of the application, as shown in the screenshot below.
In some cases, such as when using the application on mobile devices, the perspective switch is not available. In these cases, you can open the folder menu located in the upper-right part of the screen. From this menu, you can choose from the available perspectives, similar to the previous screenshot.
:::tip
Every folder can have its own **[default perspective](/folders/#default-folder-perspective)**, which can be selected in the folder properties area. Once you choose a perspective, every time you open that folder, it will be displayed using the selected perspective.
:::
## Custom Perspective Settings Per Folder
In the PRO version, you can assign a default perspective to any folder so that every time you open the folder, it will automatically be displayed using the selected perspective.
Some perspectives support custom settings at the folder level. For example, you can set custom _sorting_, _thumbnail mode_, or _pagination limits_. You can learn more in the [perspective settings](/perspectives/grid/#perspective-settings) section.
---
## Create Files
# Creating and Importing Files
In addition to previewing various file types, TagSpaces also allows you to create new files in several text-based formats, making it a great note-taking application.
To create a new file in TagSpaces, you have several options. The easiest way is to click the plus icon button, which is almost always visible in the application.
This opens the content creation menu, where you can choose from the actions described bellow.
**Timestamp as Default Tag**
When you create a new file in TagSpaces, a timestamp in the format `YYYYMMDDThhmmss` is automatically added as a tag:
- `YYYY`: The current year
- `MM`: The current month
- `DD`: The current day
- `T`: A delimiter between the date and time
- `hh`: The hour
- `mm`: The minute
- `ss`: The second
For example, a file created on January 17, 2017, at 10:30:32 would have the timestamp tag `20170117T103032`.
These timestamp tags ensure the uniqueness of automatically generated file names.
**Creating files in the desktop app**
On the desktop version of the app, you can open the **Main Menu** (by pressing `ALT` on Windows or Linux) and then select **New File** from the **File menu**.
In the tray menu there is also an entry called **New file** which will open the dialog for creating new markdown files.
## New Plain Text File
Creates a plain text file with the `.txt` extension.
## New Markdown File
Creates a text file with the `.md` extension, which ill allow you to add content [Markdown](https://en.wikipedia.org/wiki/Markdown) format.
## New HTML File
Creates an HTML file with the `.html` extension, allowing you to add rich text content.
At the top of the file creation dialogs, the automatically generated file name is displayed. The text is preselected, so you can easily change it to whatever you need. This is especially useful when creating new cards in the Kanban perspective. Below the text field, you will see the path where the file will be created. The default path is usually the current folder, but if no location is open, the file will be created in the root folder of the first location in your location manager.
The file name follows this format: `note[20191113T164613].md` (or `.html` or `.txt`). The default file name includes a timestamp tag, which is explained bellow.
## New Link File
Create a URL file, which contain a link to a web site. This files are supported natively on Mac and Windows. There are suitable for creating bookmarks.
:::tip
The created link files can be then opened in TagSpaces with the [URL Viewer](/extensions/url-viewer/) extension.
:::
## New Audio File
Opens a dialog where you can record an audio note.
:::tip
The recorded audio files can be played in TagSpaces with the [Media Player](/extensions/media-player/) extension.
:::
## New From Template
Opens a dialog where you can create files from different templates.
:::info
The file template are completely customizable in the settings of the application. Just click the **Manage templates** button in the top of the dialog to open the [**file templates tab**](/ui/settings#file-templates) in the settings.
:::
## New Form Device
Allows you to import files into the app. See the [Importing Files](#importing-files) section for more details.
## New From URL
Opens a dialog where you can enter a URL in the text field and click the **OK** button to start the download and save the file in the current folder.
:::info
Downloading files from URLs generally works for files shared from object stores, but often fails due to CORS restrictions implemented by websites. As a workaround, you can use our **[browser extension](/web-clipper/)**.
:::
## New Folder
Opens the dialog for creating new folders, where beside the name you can choose also the folder's background color.
## Importing Files
TagSpaces offers several ways to import files. After a successful import, the file will be copied to the currently open folder.
### Importing from the Folder Menu
You can also import files from the folder menu, located in the top-right corner of the application.
Choose **New From Device** to open your operating system's file chooser. From there, select the files you want to import.
### Importing Files on Mobile Devices
On mobile devices, tapping the **New From Device** menu opens a dialog that lets you choose various sources for files. In the following screenshot from an **Android** device, you can see options like:
- **Camera**: Opens the _Camera app_ to take a picture and import it into the current location.
- **Camcorder**: Allows you to record a video that can be imported into the app.
- **Voice Recorder**: Launches the _Voice Recorder app_ to create an audio note that can be imported.
- **Files**: Opens the _Files app_ to select files for import.
Depending on your Android device and installed apps, this dialog may display more or fewer options.
On **iOS**, you have the options to take a picture with the _Camera app_ or select one or more files from the _Files app_.
:::info
If the current folder is located on object storage (e.g., AWS S3), importing will trigger the file's upload to the S3 bucket.
:::
### Importing via Drag and Drop
You can also import files by dragging them from your desktop or file manager and dropping them into the app.
:::note
If the current folder is located on object storage (e.g., AWS S3), dragging and dropping files will trigger their upload to the S3 bucket.
:::
---
## Command Line Tools
This is a set of command line tools which can create search index and thumbnails for folders used in the TagSpaces Desktop and Web apps. The source code for the tools is available on [GitHub](https://github.com/tagspaces/tagspaces-common/tree/develop/packages/tagspaces-shell)
## Installation
```
npm install -global @tagspaces/shell
```
## Search index generation
This tool will create a search index for a given folder with all its sub folders.
Run node script:
```
tscmd -m indexer /some/folder/
```
This command can be used for automation e.g. in CRON jobs.
## Thumbnail generation
This script will recursively create thumbnails for a specified folder with all its sub folders.
You have to install [sharp](https://sharp.pixelplumbing.com/install) package globally with the following command:
```
npm i sharp -g
```
Set NODE_PATH environment points to global npm folder:
```
export NODE_PATH=$(npm root --quiet -g)
```
Run node script:
```
tscmd -m thumbgen /some/folder/
```
This command can be used for automation e.g. in CRON jobs.
Don't forget to put the trailing slash after the folder name.
## Cleaning obsolete thumbnails and sidecar files.
Running this command will analyze the specified folder:
```
tscmd -m metacleaner /some/folder
```
Where `-m` is for mode, which here is metacleaner. The metacleaner will analyse first the specified folder and deliver a list with files which are not needed or connected anymore. You can review the list and confirm the deletion by setting the `-a`, which is for analyse with `false` as parameter. So this command will finally perform the cleaning.
```
tscmd -m metacleaner -a false /some/folder
```
## Third party tools
Here you will find a list of projects which provides tooling compatible with TagSpaces. These projects are not affiliated with TagSpaces.
- [TSS](https://github.com/nahoj/tss) - a command-line tool to manage files with tags, with completion provided for zsh.
---
## Deployment Strategies
## Deployment of the desktop app
## Deployment of the web app
## Deployment of both app types
The following diagram shows the different ways for using the TagSpaces desktop application in combination with different deployment of the TagSpaces Web application.
---
## Extension development guide
:::caution
This guide is outdated, please use it with caution.
:::
This is an initial version of a guide intended to clarify the process of extension development for TagSpaces.
## Prerequisites
Cloning the TagSpaces repository from Github
git clone https://github.com/tagspaces/tagspaces.git
## Setting up the development environment
Using the script `checkoutextensions.sh` or `checkoutextensions.cmd` respectively for Linux and Windows.
For Windows users, please open your Command Prompt and execute the following command: checkoutextensions.cmd
For Linux users, please open your Terminal and execute the following command: sh checkoutextensions.sh
## Directory structure
After running the checkout script your dev environment should have the following directory structure:
```
~ tagspaces-github-location
├── data
│ ├── assets
│ │ └── ubuntu-font
│ ├── chromium
│ ├── cordova
│ │ └── fastclick
│ ├── electron - Electron framework core
│ ├── ext
│ │ ├── editorHTML -> tagspaces-github-location/extensions/editorHTML
│ │ ├── ...
│ │ ├── perspectiveGraph -> tagspaces-github-location/extensions/perspectiveGraph
│ │ ├── ...
│ │ ├── viewerAudioVideo -> tagspaces-github-location/extensions/viewerAudioVideo
│ │ └── ...
│ ├── js
│ ├── libs
│ │ ├── bootstrap
│ │ ├── ...
│ │ └── underscore
│ ├── locales
│ │ ├── de
│ │ ├── ...
│ │ └── zh_TW
│ ├── _locales
│ │ ├── de
│ │ ├── ..
│ │ └── zh_TW
│ ├── mozilla
│ ├── node_modules
│ │ └── fs-extra
│ ├── node-webkit
│ ├── locales
│ └── node_modules
│ ├── fs-extra
│ └── trash
├── docs
├── extensions
│ ├── editorHTML
│ ├── ...
│ ├── perspectiveGraph
│ ├── ...
│ ├── viewerAudioVideo
│ └── ...
└── node_modules
```
Please note that after running the script all extension folders in `data/ext` are connected by symlinks to the extensions in the `extensions`. In this folder you will find cloned the repositories of all supported TagSpaces extension. This way you can make changes in for e.g. `extensions/viewerImage`, which will be immediately testable after running the application, because of the symlink.
## Extension initialization
On application loading TagSpaces is scanning the extension folder (e.g. `data/ext`) for available extensions. So basically it is searching every sub folder for a bower file. From the bower file TagSpaces is extractiong the id and the name of the extension, which are needed later. Currently on Firefox and Chrome the available extensions are fixed in settings and not resolved at runtime.
When a given extension is needed, TagSpaces is loading a file called `extension.js` from the folder of the extension. So this file is mandatory for every extension. It loads later with _requirejs_ further javascript, css or other types of files if needed.
In the most extensions like [viewerImage] or [viewerMD] the `extension.js` is creating dynamically a new IFRAME elements which loads a file called `index.html`, where the image or markdown content is displayed or manipulated.
## Messaging API
In order the extension to communication with TagSpaces the _Messaging API_ can be used. It is currently in definition phase and can be found unter [data/js/ext.api.js](https://github.com/tagspaces/tagspaces/blob/master/data/js/ext.api.js)
## Structure of the extension
The following is the structure of a typical extension.
.
├── bower.json - A mandatory file
├── .bowerrc - An optional file for specifying the location of the libraries (e.g. ./libs folder)
├── extension.css
├── extension.js - the app is searching on extension loading js file with this name.
├── main.js -
├── index.html
├── libs
│ ├── exif-js
│ │ ├── bower.json
│ │ ├── ...
│ │ └── exif.js
│ ├── jquery
│ │ ├── bower.json
│ │ ├── dist
│ │ │ ├── jquery.js
│ │ │ └── jquery.min.js
│ │ └── MIT-LICENSE.txt
│ └── jquery.panzoom
│ ├── bower.json
│ ├── ...
│ └── dist
│ ├── ...
│ └── jquery.panzoom.min.js
├── LICENSE.txt
├── locales - location of the translated files from Transifex
│ ├── de_DE
│ │ └── ns.viewerImage.json
│ ├── ...
│ └── en_US
│ └── ns.viewerImage.json
└── README.md
## Recommended structure of the bower.json
TagSpaces uses Bower as a management tool for its extension. In this section you will find out how the mandatory bower.json should look like.
```js {2}
{
"name": "The Cool Name", <- The name of the extension, can contain spaces
"id": "viewerHTML", <- The id of the extension, should be the same as the folder where your ext. is located
"description": "A TagSpaces extension for ...", <- Short description of your extension
"type": "viewer", <- The type of your extension, could be: viewer, editor or perspective
"version": "1.0.0", <- The version of the extension
"dependencies": {
"jquery.panzoom": "~2.0.5"
},
"devDependencies": {},
"authors": [
"Your Name Here - http://your-optional-website-or-email.com"
],
"keywords": [
"html",
"viewer"
],
"license": "MIT",
"main": [
"extension.js"
],
"ignore": [
"Gruntfile.js"
],
"private": true
}
```
## Internationalization
For the internationalization of the extensions we use [Transifex](https://www.transifex.com/tagspaces/tagspaces/). For some extension we have already created translation file, like for [viewerImage](https://www.transifex.com/tagspaces/tagspaces/nsviewerimagejson/)
---
## External Configuration
## Introduction
This document will describe how to deploy TagSpaces Pro and Custom with predefined configuration such as custom logo and color, tag library or locations. The settings discussed here should be saved in a file called **extconfig.js**, placed in the folder where the application is hosted.
## Configuring a custom logo
For exchanging the application logo the **ExtLogoURL** parameter should be used. A valid values can be an URL:
```js title="Add custom logo"
window.ExtLogoURL = "https://www.tagspaces.org/content/text-logo.svg";
```
or a relative path the file containing the logo:
```js
window.ExtLogoURL = "custom-logo.png";
```
:::tip
Images with up to **250 px** width and up to **50 px** height suits best in the user interface of the application. Valid image file formats are JPG, GIF, PNG and SVG.
:::
## Hiding TagSpaces' logo
The following setting can be used in order to hide the TagSpaces' logo in the upper left part of the user interface.
```js
window.ExtShowTSLogo = false;
```
Possible values: `true`, `false`. Default value: `true`
## Hiding TagSpaces' version
The following setting can be used in order to hide the TagSpaces' version in the upper left part of the user interface.
```js
window.ExtShowTSVersion = false;
```
Possible values: `true`, `false`. Default value: `true`
## Disabling the onboarding dialog and the license confirmation
The property **ExtIsFirstRun** can be used for disabling the initial onboarding dialog and license confirmation.
```js
window.ExtIsFirstRun = true;
```
The default value is `true`.
## Disable the checking for new version on startup
```js
window.ExtCheckForUpdatesOnStartup = false;
```
The default value is `true`.
## Switching desktop and mobile mode of the app
The property **ExtDisplayMode** can be used for switching between the desktop and mobile mode of the app.
```js
window.ExtDisplayMode = "mobile";
```
Possible values are `mobile` and `desktop`.
## Specifying the file tagging mode in the app
The property **ExtUseSidecarsForFileTagging** can be used for switching between using the file rename method and using sidecar files for saving the tagging information.
```js
window.ExtUseSidecarsForFileTagging = false;
```
Possible values are `true` and `false`.
:::tip
If the parameter is specified then this setting could not be changed in the TagSpaces settings dialog anymore. The user can only see which file tagging method is activated (renaming files or using sidecar files)
:::
## Forcing the user to use tags from the tag library only
If the property **ExtUseOnlyTagsFromTagLibrary** is set to true, the user is forced to limit the tagging only with the predifined tags. The freely creation of tags during tagging is prohibeded this way.
```js
window.ExtUseOnlyTagsFromTagLibrary = false;
```
Possible values are `true` and `false`.
:::tip
If the parameter is specified then this setting could not be changed in the TagSpaces settings dialog anymore. The user can only see the current status of the setting.
:::
## Specifying the location of the tags in the filename
The property **ExtFilenameTagPlacedAtEnd** can be used to switching between placing the tags in the beginning of the filename or in the end. For example: `[tag1 tag2] filename.ext` vs. `filename [tag1 tag2].ext`.
```js
window.ExtFilenameTagPlacedAtEnd = true;
```
Possible values are `true` and `false`. The default value is `true`.
## Configure custom URLs
### Custom privacy policy URL
The installation of TagSpaces Web and TagSpaces Web Pro, do not show a button leading to a privacy policy by default. An URL to a custom privacy policy can be configured with this setting:
```js
window.ExtPrivacyURL = "https://tagspacesweb.yourdomain.com/privacy/";
```
### Custom imprint page URL
The installation of TagSpaces Web and TagSpaces Web Pro, do not show a button leading to a imprint web page by default. An URL to a custom imprint page can be configured with this setting:
```js
window.ExtImprintURL = "https://tagspacesweb.yourdomain.com/imprint/";
```
## Configuring custom locations
With this feature TagSpaces can be deployed with a set of predefined location, which could point to local folder or object store buckets hosted for example on AWS S3. The configuration property responsible for this feature is called **ExtLocations**.
This an example for connecting an AWS S3 bucket as location:
```js title="extconfig.js"
window.ExtLocations = [
// a list containing one or many locations
{
uuid: "10565f09-c7fd-2333-fc67-a75db27rt5ba", // an inique id of the location
type: "1", // 1 defines the locations a cloud based
name: "The name of the cloud location", // the name of the location
path: "demo", // the path to sub folder in the location
accessKeyId: "your_access_key", // the access key of the user
secretAccessKey: "your_secret_key", // the secret case of the user
bucketName: "demo-bucket", // the name of the S3 bucket
region: "eu-central-1", // the AWS region
endpointURL: "https://nas34r:3000/minio", // optional property allowing the specify the cloud end-point directly
isNotEditable: true, // disable the opening of the location properties and export
isDefault: true, // if true this location will be loaded by the application start
isReadOnly: true, // if true the user interface of the application turns to read-only mode
disableIndexing: false, // if "true" the app will try to find an existing search index and use it for the searches, by "false" the app will create the index on every search (unless the last created index in the current browser session is not expired see maxIndexAge property)
disableThumbnailGeneration: false, // disables the process of thumbnail generation, usefull for S3 buckets, where you do not want to dowload the folder content in order to generate thumbnails
fullTextIndex: false, // activated the full-text search for TXT, MD and HTML files
watchForChanges: false, // activates the watching for changed files in the current location, (feature is not working on cloud locations)
maxIndexAge: 600000 // time in milliseconds (10 minutes x 60 secs per minute x 1000 milliseconds per second) for which the index is valid
persistTagsInSidecarFile: true // specifies the way files are tagged in this location
ignorePatternPaths: ["**/node_modules/**"], // list of path strings to ignore while indexing
},
];
```
The following snipped is an example for connecting a local folder as location:
```js
window.ExtLocations = [
// an array containing one or many locations
{
uuid: "53453458-c7fd-2333-fc67-a75db27rt5ba", // an unique id of the location
type: "0", // 0 defines the location as local
name: "The name of the local location", // the name of the location
paths: ["/var/mnt/data/"], // the path pointing to the local folder
isDefault: true, // if true this location will be loaded by the application start
isReadOnly: true, // if true the user interface of the application turns to read-only mode
disableIndexing: false, // if "true" the app will try to find an existing search index and use it for the searches, by "false" the app will create the index on every search (unless the last created index in the current browser session is not expired see maxIndexAge property)
fullTextIndex: false, // activated the full-text search for TXT, MD and HTML files
watchForChanges: false, // activates the watching for changed files in the current location
},
];
```
### Disable the editing of the locations (deprecated)
The editing of the locations can be disabled with the following property: **ExtLocationsReadOnly**
:::tip
This switch is not supported anymore. Now as soon as you have externally configured locations they are automatically read-only.
:::
### Saving locations in the browser
Turning on this property will force the app to store the configuration for the locations in the browser's local storage. In the desktop app this is enabled by default, but on the web based version it is turned off.
```js
window.ExtSaveLocationsInBrowser = true;
```
Possible values are `true` and `false`. Default value is `false`
You might want to set this setting to true, if you want the location data, including the access and secret key for accessing S3 based locations is saved in the local storage of your browser. This way, you don't have to recreate the location every time you open the application.
If you are using TagSpaces Web in a browser on your computer or mobile device, where only you have access, this shouldn't be a problem. Please keep in mind, anybody with access to your browser, can with some effort get access to the access keys. This is of course true also for the desktop version, where anybody who can start TagSpaces on your computer can see this information.
:::warning
**Warning**: It is not recommended to use TagSpaces Web installations with `ExtSaveLocationsInBrowser = true` on public computers, since the location information will potentially stay there even after you close the browser.
:::
## Configuring custom tag library
With this feature TagSpaces can be deployed with a set of predefined tags distributed in tag groups. The configuration property responsible for this feature is called **ExtTagLibrary**.
The following code snipped shows how to define one tag group containing one tag as a predefined tag library
```js
window.ExtTagLibrary = [
// an array containing one or many tag groups
{
uuid: "17882854-44a7-4b2d-a2b1-b022846ac41d", // an unique id of the tag group
title: "Common Tags", // the name of the tag group
color: "#008000", // the default background color of the tags in this group
textcolor: "#ffffff", // the default text color of the tags in this group
readOnly: true, // makes the tag group read-only
children: [
// an array containing one or many tags
{
type: "plain", // the type of tag, just leave it plain
title: "book", // the name of the tag
description: "", // a optional description for a tag
color: "#008000", // the background color of the tag
textcolor: "#ffffff", // the text color of the tag
},
],
expanded: true, // should be true in order this tag group to be visible in the application
},
];
```
### Including the tag library in the config
- Start the export process from the three dot menu of the tag library
- From the export dialog choose which tag groups you want to export
- Click the **Export** button and choose where the exported json file should be saved
- Open the exported json file in text or json editor. TagSpaces has an integrated [JSON editor](https://docs.tagspaces.org/extensions/json-editor/), which can be used too.
- Edit the json files if needed
- Copy the part shown in the next snipped, to the window.ExtTagLibrary array in the extconfig.js
- Save the changes in extconfig.js
Explanation which part of the code should be copied.
```js
{
"appName": "TagSpaces",
"appVersion": "6.3.1",
"settingsVersion": 3,
"tagGroups": [
// Copy everything from here to window.ExtTagLibrary = [ here ]
]
}
```
:::tip
As soon as tags are defined in the `extconfig.js`, the tag library will rendered read-only in the application, so the user will not able to add, change or delete tags there.
:::
## Configuring search file types
With this setting you can customize the file types grouping in the search.
This is the current default configuration:
```js
window.ExtSearchTypeGroups = {
any: [''],
images: [
'jpg',
'jpeg',
'jfif',
'jif',
'jiff',
'png',
'gif',
'svg',
'webp',
'bmp',
'tga',
'tif',
'tiff',
'nef',
'cr2',
'dng',
'psd',
'avif',
'nef',
],
notes: ['md', 'mdown', 'txt', 'html'],
documents: [
'pdf',
'doc',
'docx',
'xls',
'xlsx',
'odt',
'ods',
'odp',
'pptx',
'numbers',
'potx',
'sldx',
'dotx',
],
audio: ['ogg', 'mp3', 'wav', 'wave', 'flac', 'acc', 'm4a', 'opus'],
video: ['ogv', 'mp4', 'webm', 'm4v', 'mkv', 'avi', '3gp', '3g2', 'mov'],
archives: ['zip', 'rar', 'gz', 'tgz', 'arc', '7z'],
bookmarks: ['url', 'lnk', 'sym', 'desktop', 'website'],
ebooks: [
'epub',
'mobi',
'azw',
'prc',
'azw1',
'azw3',
'azw4',
'azw8',
'azk',
],
emails: ['eml', 'msg'],
folders: ['folders'],
files: ['files'],
untagged: ['untagged'],
};
```
## Configuring custom search queries
TagSpaces Pro can be pre-configured with predefined search queries.
```js
window.ExtSearches = [
// a list of search queries
{
uuid: "2123", // unique identifier
title: "Some query name", // name of the search
textQuery: "", // some free text query
fileTypes: "", // possible values
tagsAND: [
// all of these tags should be attached to an entry
{
title: "tag1",
},
{
title: "tag2",
},
],
tagsOR: [], // at least one of those tags should be attached to an entry
tagsNOT: [
// none of these tags should be attached to an entry
{
title: "tag3",
},
],
lastModified: "",
fileSize: "",
searchBoxing: "location", // other possible values are 'folder' or 'global'
searchType: "fuzzy", // other possible values are 'semistrict' or 'strict'
forceIndexing: true, // re-index the current location before performing the search
currentDirectory: "/home/username/Documents",
fileTypes: ["md", "mdown", "txt", "html"], // a list of file extensions
lastModified: "past7Days", // TBD
fileSize: "sizeVerySmall", // TBD
tagTimePeriodFrom: 1622505600000, // TBD
tagTimePeriodTo: 1625090399999, // TBD
maxSearchResults: 100, // max number of search result
showUnixHiddenEntries: true, // TBD
},
];
```
## Configuring custom map tile servers
From version 3.10 TagSpaces can be pre-configured with custom map tile servers. The OpenStreetMap compatible tile servers can be even self hosted allowing you to work with maps without the need to be connect to the Internet.
```js
window.ExtMapTileServers = [
// a list of one or more external map tile server with their attributes
{
uuid: "qer4123412ew", // an unique id of the map tile server
name: "Stamen Watercolor",
serverURL:
"https://stamen-tiles.a.ssl.fastly.net/watercolor/{z}/{x}/{y}.jpg",
serverInfo:
"Map tiles by Stamen Design - http://stamen.com, under CC BY 3.0. Data by OpenStreetMap, under CC BY SA.",
},
];
```
:::tip
Some example map tile servers can be found in the [OpenStreetMap Wiki](https://wiki.openstreetmap.org/wiki/Raster_tile_providers). Please consider the terms of usage of any given map service provider!
:::
## Configure the format of the geo tags
The geo tags in can be in either in [Pluscode](https://en.wikipedia.org/wiki/Open_Location_Code) or in [MGRS](https://en.wikipedia.org/wiki/Military_Grid_Reference_System) formats.
```js
window.ExtGeoTaggingFormat = "pluscodes";
```
Possible values: `pluscodes`, `mgrs`.
## Configure the boundaries of the default map
With this parameter you can configure a map rectangle, which will be loaded by default in the Mapique perspective the current folder does contain any geo-tagged files or folders.
```js
window.ExtDefaultMapBounds = {
southWest: { lat: 56, lng: -13 },
northEast: { lat: 29, lng: 50 },
}
```
The geo coordinates in the example above are the default ones, will open Europe in the map.
{/* ## Configuring third-party extensions
```js
window.ExtExtensionsFound = [
{
extensionId: '@tagspaces/arithmetic-player',
extensionName: 'Mental Arithmetic',
extensionTypes: ['viewer'],
extensionEnabled: true,
version: '1.0.0',
},
];
```
```js
window.ExtSupportedFileTypes = [
{
type: 'math',
color: '#5cb85c',
viewer: 'third-party/extensions/@tagspacesarithmetic-player_1.0.0/build',
},
];
``` */}
## User interface tweaks
### Show vertical panel on startup (deprecated)
```js
window.ExtDefaultVerticalPanel = "none";
```
Possible values: `none`, `taglibrary`, `locations`
{/* ### Show advanced search (removed with version 5.4 )
```js
window.ExtShowAdvancedSearch = true;
```
Possible values: `true`, `false`. Default value: `true`. */}
### Show welcome panel
```js
window.ExtShowWelcomePanel = true;
```
Possible values: `true`, `false`. Default value: `true`.
### Show smart tags
Smart tags are documented [here](/ui/taglibrary/#smart-tags).
```js
window.ExtShowSmartTags = true;
```
Possible values: `true`, `false`. Default value: `true`.
### Enable location based tags
The [location tags](/ui/taglibrary/#location-tags) are saved in the location's folder and not centrally in the applicaiton's configuration.
```js
window.ExtUseLocationTags = true;
```
Possible values: `true`, `false`. Default value: `false`.
### Author
This setting provides a way to overwrite the author name which is by default the username of the operating system. The author name can be used in the templates.
```js
window.ExtAuthor = '';
```
Possible values: `true`, `false`. Default value: `true`.
## Theming
### Choose startup theme
```js
window.ExtTheme = "dark";
```
Possible values: `dark`, `light`.
### Open app with predefined perspective
```js
window.ExtDefaultPerspective = "gallery";
```
Possible values are `default`, `gallery`, `mapique`.
## Custom color for the default themes
### Set custom light color for the light theme
```js
window.ExtLightThemeLightColor = "#dcf3ec";
```
Possible value: any css color
Default value: `'#dcf3ec'`
### Set custom main color for the light theme
```js
window.ExtLightThemeLightColor = "#1dd19f";
```
Possible value: any css color
Default value: `'#1dd19f'`
### Set custom light color for the dark theme
```js
window.ExtDarkThemeLightColor = "#56454e";
```
Possible value: any css color
Default value: `'#56454e'`
### Set custom main color for the dark theme
```js
window.ExtDarkThemeMainColor = "#ff9abe";
```
Possible value: any css color
Default value: `'#ff9abe'`
{/* ### Set custom sidebar color (obsolete since v4)
```js
window.ExtSidebarColor = "#2C001E";
```
Possible value: any css color
Default value: '#2C001E'
### Set custom sidebar selection color (obsolete since v4)
```js
window.ExtSidebarSelectionColor = "#880E4F";
```
Possible value: any css color
Default value: '#880E4F' */}
## Custom prompts for AI functionalities
### Default question prompt
```js
window.ExtDefaultSystemPrompt = "Given the following conversation and a follow up question, rephrase the follow up question to be a standalone question. Chat History: {chat_history} Follow Up Input: {question} Standalone question:";
```
### Prompt for summary generation
```js
window.ExtSummarizePrompt = "Generate a concise summary {max_chars} in {language} language for the following text: {summarize_text}";
```
### Prompt for generation of structured description for an image
```js
window.ExtDescriptionFromImageStructuredPrompt = "Analyze this image and return a detailed JSON description including objects, scene, colors and any text detected. If you cannot determine certain details, leave those fields empty.";
```
### Prompt for generation of description for an image
```js
window.ExtDescriptionFromImagePrompt = "Generate a concise description for this image {file_name} in {language} language.";
```
### Prompt for generation of description for text
```js
window.ExtDescriptionFromTextPrompt = "Generate a concise description {max_chars} in {language} language for this text: {input_text}.";
```
### Prompt for generating tags from image
```js
window.ExtTagsFromImagePrompt = "Write the most important topics from the image description. The output TOPICS must be in parsable format like {keyword} without whitespace in braces.";
```
### Prompt for generating tags from text
```js
window.ExtTagsFromTextPrompt = "Extract important tags (single words please) and sort them by their importance from the following content: {input_text}";
```
## Custom templates for new files
### Default new file template
```js
window.ExtDefaultFileTemplate = {
id: 'default',
name: 'Default',
content: '{createdInApp} ({date})',
fileNameTmpl: 'note[{timestamp}]',
};
```
### Defining a set of templates for new files
```js
window.ExtFileTemplates = [
{
id: '62342',
name: 'External Template 1',
description: 'Default template for new markdown files'
type: 'md', // md | txt | html
content: '{createdInApp} ({date}) by {{author}},
fileNameTmpl: 'task[{timestamp}]',
screenshotUrl: 'dataURL:...', // URL to a screenshot of the template
},
{
id: '72323',
name: 'External Template 2',
description: 'Default template for new text files'
type: 'txt', // md | txt | html
content: '{createdInApp} ({date})',
fileNameTmpl: 'issue[{timestamp}]',
screenshotUrl: 'dataURL:...', // URL to a screenshot of the template
}]
```
## Embedding extconfig.js to packages
### For macOS
- Open the TagSpaces' DMG package
- Copy the content `TagSpaces.app` to a folder e.g. your desktop
- Navigate to TagSpaces.app/Contents folder and copy there your `extconfig.js` file
- Install TagSpaces.app to your Applications folder with simple drag and drop
Allternatively you can copy the `extconfig.js` after the installation to this path: `/Applications/TagSpaces.app/Contents`
### For Windows
- Extract the content of TagSpaces' ZIP package to a folder e.g. your desktop
- Copy the `extconfig.js` in the extracted folder
- Zip the folder and redistribute
Alternatively copy the `extconfig.js` directoy to the installation folder, as shown in the following screenshot. The path is usually `C:\Users\USERNAME\AppData\Local\Programs\TagSpaces`.
### For Linux
- Extract the content of TagSpaces' TAR.GZ package to a folder e.g. your desktop
- Copy the `extconfig.js` in the extracted folder
- Zip the folder and redistribute
## Example configuration file
Here you will find the whole configuration file, so it can be easily copied and reused for your custom needs.
```json{2}
window.ExtLogoURL = "https://www.tagspaces.org/content/text-logo.svg";
window.ExtIsFirstRun = false;
window.ExtTheme = "dark";
window.ExtLocations = [
{
uuid: "10565f09-c7fd-2333-fc67-a75db27rt5ba",
type: "1",
name: "The name of the cloud location",
path: "demo",
accessKeyId: "your_access_key",
secretAccessKey: "your_secret_key",
bucketName: "demo-bucket",
region: "eu-central-1",
isDefault: false,
isReadOnly: true,
disableIndexing: false,
fullTextIndex: false,
watchForChanges: false,
},
{
uuid: "53453458-c7fd-2333-fc67-a75db27rt5ba",
type: "0",
name: "The name of the local location",
path: "/var/mnt/data/",
isDefault: true,
isReadOnly: true,
disableIndexing: false,
fullTextIndex: false,
watchForChanges: false,
},
];
window.ExtTagLibrary = [
{
uuid: "17882854-44a7-4b2d-a2b1-b022846ac41d",
title: "Common Tags",
color: "#008000",
textcolor: "#ffffff",
children: [
{
id: "ff47282f-a7cc-474c-951f-4636d60c0529",
type: "plain",
title: "book",
description: "",
color: "#008000",
textcolor: "#ffffff",
},
{
id: "c3fa72f5-afde-4d2e-af14-bdebb6782a71",
type: "plain",
title: "article",
description: "",
color: "#008000",
textcolor: "#ffffff",
},
],
},
{
uuid: "e21711da-ee78-4c83-bae3-e0007fe426a3",
title: "Priorities",
color: "#008000",
textcolor: "#ffffff",
children: [
{
id: "dca64cf4-79e2-4450-a57b-b53d9d6b8ad3",
type: "plain",
title: "high",
description: "",
color: "#ff7537",
textcolor: "#ffffff",
},
{
id: "41dbf6ab-cf8f-4d88-bad1-f9baec83d48b",
type: "plain",
title: "medium",
description: "",
color: "#ffad46",
textcolor: "#ffffff",
},
{
id: "78fb6569-9970-4fdf-b6df-ec0daa6ea9b9",
type: "plain",
title: "low",
description: "",
color: "#7bd148",
textcolor: "#ffffff",
},
],
},
];
```
---
## Specification of the meta file formats
In comparison to many other tools, TagSpaces uses external text files for saving the meta information for folders and files, instead of a database. Here you will find the specification of the formats used by these files and also some other useful information concerning these files.
## Role of the meta folder
The folder containing the meta information for given folder is called `.ts`. The dot in front of the name makes this folder automatically hidden for Unix based file systems like Linux or MacOS. On Windows we set explicitly the a flag to make this folder hidden. Every folder managed in TagSpaces will have its own meta folder.
The meta folder contains the following files:
- **[tsm.json](#folder-meta-description-format)** - contains the meta information for the parent folder of the `.ts` folder
- **tsi.json** - contains the search index for the parent folder it is a root of a location
- **tst.jpg** - is the thumbnail file of the parent folder
- **tsb.jpg** - is the background image file of the parent folder
- **[tsl.jpg](#format-of-the-location-specific-tag-groups)** - contains location specific tag groups, if the parent folder is the root of a location
- **file1.ext.jpg** - every file in the parent folder can have a thumbnail which is saved in this file (if the main fail is called `document.pdf` the thumbnail file will be named `document.pdf.jpg`)
- **[file1.ext.json](#file-meta-description-format)** - every file in the parent folder can have its own meta information which is save in this files (the main file is called `file.ext`)
## File meta description format
This file should be located in a folder called `.ts` located in the folder, where the tagged file is placed. The meta file should have exactly the same name as the tagged file, but in addition it should have the `.json` file extension. So at the end you should have similar structure as the following:
```
~ /some/TagSpaces/location/folder
├── subfolder_1
│ ├── .ts
│ │ ├── file1.jpg.json
│ │ └── file2.pdf.json
│ ├── file1.jpg
│ └── file2.pdf
├── .ts
│ ├── file3.png.json
│ └── file4.docx.json
├── file3.png
└── file4.docx
```
The meta information is saved in JSON format, which has the following format:
```json title="Example JSON file containing file meta data"
{
"id": "4194969c6bb84ad3acac779645c90e70",
"tags": [
// A set containing the file tags
{
"title": "tag1", // The name of the tag
"type": "sidecar", // The type of the tag
"color": "#ffcc24", // The background color of the tag
"textcolor": "#ffffff" // The text color of the tag
},
{
"title": "tag2",
"type": "sidecar",
"color": "#ffcc24",
"textcolor": "#ffffff"
}
],
"description": "# Some description\n\nin *markdown* format" // \n is used for adding new line
}
```
## Folder meta description format
In the PRO version of the application you can add tags and description to every folder managed in TagSpaces. This meta information is persisted in a file called **tsm.json** located in `.ts` folder of the tagged folder. The following is an example folder structure of a tagged folder with one tagged subfolder.
```
~ /some/TagSpaces/location/folder
├── subfolder_2
│ ├── .ts
│ │ ├── tsm.json // a file containing the meta info for subfolder_2
│ │ └── file2.pdf.json
│ └── file2.pdf
├── .ts
│ ├── tsm.json
│ └── file4.docx.json
└── file4.docx
```
The meta information is saved in JSON format, which has the following format:
```json title="Example tsm.json file containing folder meta data"
{
"id": "6622238f41024c1a934948abe2e56540", // id of folder
"color": "#a47ae244", // the background color of the folder
"description": "# Some description\n\nin *markdown* format", // \n can be used for adding new line
"tags": [
// the tags added to the folder
{
"title": "1926", // tag name
"type": "sidecar", // tag type
"color": "#cca6acff", // tag background color
"textcolor": "white" // the color of the text in the tag
},
{
"title": "3star",
"type": "sidecar",
"color": "#ffcc24",
"textcolor": "#ffffff"
}
],
"perspectiveSettings": {
"list": {
// the List perspective settings of the current folder
"testID": "listPerspectiveContainer",
"settingsKey": "tsPerspectiveList",
"orderBy": true,
"sortBy": "byName",
"layoutType": "row",
"singleClickAction": "openInternal",
"entrySize": "tiny",
"thumbnailMode": "contain",
"showDirectories": true,
"showDetails": true,
"showDescription": false,
"showEntriesDescription": true,
"showTags": true,
"gridPageLimit": 100,
"maxDescriptionPreviewLength": 100
},
"grid": {
// the Grid perspective settings of the current folder
"testID": "gridPerspectiveContainer",
"settingsKey": "tsPerspectiveGrid",
"orderBy": true,
"sortBy": "byName",
"layoutType": "grid",
"singleClickAction": "openInternal",
"entrySize": "small",
"thumbnailMode": "cover",
"showDirectories": true,
"showDetails": true,
"showDescription": false,
"showEntriesDescription": true,
"showTags": true,
"gridPageLimit": 100,
"maxDescriptionPreviewLength": 100,
"nativeDragModeEnabled": false
},
"kanban": {
// the Kanban perspective settings of the current folder
"settingsKey": "tsKanBanPerspective",
"orderBy": true,
"sortBy": "byName",
"layoutType": "grid",
"singleClickAction": "openInternal",
"entrySize": "small",
"thumbnailMode": "contain",
"showDirectories": true,
"showDetails": true,
"showSubFolderDetails": false,
"showEntriesDescription": false,
"showFolderContent": false,
"showTags": true,
"filesLimit": 15,
"initColumnsLimit": 5
}
},
"customOrder": {
// order of the files (cards) and folders (columns) used in Kanban perspective
"folders": [
{ "uuid": "6622238f41024c1a934948abe2e56540", "name": "Folder1" },
{ "uuid": "02a2a158c17b4b7bb45a583bd5029e28", "name": "Folder2" },
{ "uuid": "f367e3cf8958471aa8d8ae9076ceb6cb", "name": "Folder3" }
],
"files": [
{
"uuid": "02c5a465b3164110bd6ad3a1721ed27a",
"name": "file1.png"
},
{
"uuid": "f3b6b54e394849d59a9a77ebeaed8a5a",
"name": "file2.mp4"
},
{
"uuid": "eead6bac508f4634abde93921fc11a37",
"name": "file3.pdf"
}
]
}
}
```
> **Note** In the JSON examples on this page, you will find sometimes a description after the these characters `//`. These are not part of the format and are used only for clarification purposes.
## Format of the tag library export
All tag groups and tags can be exported from the settings of the application, as shown in the next screenshot.
The meta information is persisted in JSON format, which has the following format:
```json title="Example tag library export file in JSON format"
{
"appName": "TagSpaces", // the app name from which this file was generated
"appVersion": "6.4.5", // the version of the app from which this files was generated
"settingsVersion": 3,
"tagGroups": [
// a list of one or more tag groups
{
"created_date": "1728677734620", // the time when this tag group was created
"uuid": "5d8e8305a3ba4fa394fdbb13823dce6d", // an universally unique of the tag group
"title": "TestTG", // the name of the tag group
"color": "#fa573cff", // the default color of the tags in this tag group
"textcolor": "white", // the default text color of the tags in this tag group
"children": [
// a list of one or more tags in the current tag group
{
"title": "tag1", // the name of the tag
"description": "", // maybe used in the future
"color": "#fa573cff", // the color of the tag
"textcolor": "white", // the text color of the tag
"description": "some description" // description of the tag
},
{
"title": "tag2",
"color": "#fa573cff",
"textcolor": "white"
}
],
"modified_date": "1744893534077",
"expanded": false
},
{
"uuid": "e28bd828c1e445ed810ac660609f9780",
"title": "Another tag group", // the name of the second tag group in the list
"color": "#cca6acff",
"textcolor": "white",
"children": [
{
"type": "sidecar",
"color": "#cca6acff",
"textcolor": "white"
}
],
"created_date": "1744893534077",
"modified_date": "1744893534077",
"expanded": true
}
]
}
```
## Format of the location export
The locations can be exported from one TagSpaces Pro installation and imported in another. The format of the exported file is presented in this section. The example bellow specified one local and two location pointing object storages. The second one is AWS S3 object storage, while the third one is pointing to MinIO server.
```json title="Example location export file in JSON format"
{
"appName": "TagSpaces", // the app name from which this file was generated
"appVersion": "6.4.5", // the version of the app from which this files was generated
"locations": [
// a list containing one or many locations
{
"uuid": "1fa528e7-92b4-3ew2-b4b9-3cd975d87fba",
"type": "0", // 0 specifies a location pointing to a local folder
"name": "Desktop", // name of the location
"path": "/home/username/Desktop", // path pointing to a local folder, should not be empty on local locations
"isDefault": true, // specifies if this location is the default one, which loads after starting the app
"isReadOnly": false, // specified is the location should be in read-only mode
"disableIndexing": false, // if "true" the app will try to find an existing search index and use it for the searches, by "false" the app will create the index on every search (unless the last created index in the current browser session is not expired see maxIndexAge property)
"disableThumbnailGeneration": false, // disables the process of thumbnail generation, usefull for S3 buckets, where you do not want to dowload the folder content in order to generate thumbnails
"creationDate": 1743859126680, // the creation time of the location
"lastEditedDate": 1744891863809,
"fullTextIndex": false, // activated the full-text search for TXT, MD and HTML files
"maxIndexAge": 660000, // time in milliseconds (10 minutes x 60 secs per minute x 1000 milliseconds per second) for which the index is valid
"watchForChanges": true, // activates the watching for changed files in the current location
"ignorePatternPaths": ["**/node_modules/**"], // list of path strings to ignore while indexing
"persistTagsInSidecarFile": false // specifies the way files are tagged in this location
},
{
"uuid": "681c60cc-67uz-4221-aebf-f35ce797cd0c",
"type": "1", // 1 specifies a location from object storage type (cloud location)
"name": "TS Pro Releases AWS",
"endpointURL": "",
"accessKeyId": "aws_access_key_id", // access key id
"secretAccessKey": "some_secret_key", // secret key id
"encryptionKey": "some_enc_key", // key for the decryption of encrypted files
"bucketName": "your_bucket_name", // the name of the bucket in the object storage
"region": "eu-central-1", // AWS region
"isDefault": false,
"isReadOnly": true,
"disableIndexing": false,
"disableThumbnailGeneration": true,
"fullTextIndex": false,
"watchForChanges": false,
"creationDate": 1740474629766,
"lastEditedDate": 1744891863809,
"maxLoops": 2,
"path": "an_optional_path_in_the_s3_bucket"
},
{
"uuid": "2762d4e6-559b-4421-3w12-e40c967160d8",
"type": "1",
"name": "MinIO Server on QNAP NAS",
"path": "/",
"endpointURL": "http://192.168.178.12:7000", // a URL to the server (e.g. MinIO) providing the object storage
"accessKeyId": "miniouser",
"secretAccessKey": "secret_minio_password",
"bucketName": "Photos",
"region": "",
"isDefault": false,
"isReadOnly": false,
"disableIndexing": false,
"fullTextIndex": false,
"watchForChanges": false,
"creationDate": 1740474629766
}
]
}
```
## Format of the exported search queries
TagSpaces Pro offers the possibility to export previously saved search queries. And later import them in another TagSpaces Pro installation.
```json title="Example files with exported search queries in JSON format"
{
"appName": "TagSpaces",
"appVersion": "6.4.5",
"searches": [
{
"uuid": "3c5c1937043a43388f44408944ac31ba",
"title": "testquery +1920 -article |5star",
"textQuery": "testquery",
"tagsAND": [
{
"title": "1920"
}
],
"tagsOR": [
{
"title": "5star"
}
],
"tagsNOT": [
{
"title": "article"
}
],
"searchBoxing": "location", // "location", "folder" or "global"
"searchType": "fuzzy", // "fuzzy", "strict" or "semistrict"
"fileTypes": ["md", "mdown", "txt", "html"], // file extension you need can be added here
"lastModified": "past7Days",
"fileSize": "sizeVerySmall",
"tagTimePeriodFrom": 1622505600000,
"tagTimePeriodTo": 1625090399999,
"maxSearchResults": 1000,
"forceIndexing": false // true or false
}
]
}
```
## Format of the location specific tag groups
Since version 3.11 TagSpaces supports tags which are specific for a given location. The tags resides in a file called `tsl.json`, which should be located in the `.ts` folder of the current location.
```{5}
~ /some7TagSpaces/location/folder
├── subfolder_2
├── .ts
│ ├── tsm.json
│ ├── tsl.json // file containing the tag groups of this location
│ └── file4.docx.json
└── file4.docx
```
The format of these files is similar to the format of the produced by exporting your [tag library](#format-of-the-tag-library-export). So basically you can take such exports rename them to tsl.json and put them in .ts folder. After reloading them by clicking the "Reload Location Tags"-menuitem the tag-groups should appear in the Tag Library. Tag groups imported from locations will have the location name in brackets as seen the following screenshot.
```json title="Example tsl.json file"
{
"appName": "TagSpaces", // the app name from which this file was generated
"appVersion": "3.11.2", // the version of the app from which this files was generated
"tagGroups": [
// a list of one or more tag groups
{
"created_date": "1740474629766", // the time when this tag group was created
"uuid": "2e0c46f0-3a1b-4902-a930-58a0a1a170f8", // an universally unique of the tag group
"title": "TestTagGroup", // the name of the tag group
"readOnly": "true", // specifies if the tag group can be edited
"color": "#fa573cff", // the default color of the tags in this tag group
"textcolor": "white", // the default text color of the tags in this tag group
"children": [
// a list of one or more tags in the current tag group
{
"type": "sidecar",
"title": "tag1", // the name of the tag
"color": "#fa573cff", // the color of the tag
"textcolor": "white" // the text color of the tag
},
{
"type": "sidecar",
"title": "tag2",
"color": "#fa573cff",
"textcolor": "white"
}
],
"modified_date": "1740474629766",
"expanded": false
}
]
}
```
---
## Edit Files
Besides opening and viewing files, TagSpaces can also edit specific file formats. Just like [File Browser Perspectives](/browsing-files/#perspectives-overview), and [File Preview extensions](/viewing-files/), the different types of **File Editors** are also **modular extensions**, making TagSpaces' file editing capabilities extendable. Currently three editor extensions ship bundled with the application:
- [**HTML Editor**](/extensions/html-editor/) - `HTML` files serve a specific purpose in TagSpaces. They are treated as RichText documents, that can not only be previewed, but visually edited in a full-featured **WYSIWYG editor**.
- [**Markdown Editor**](/extensions/md-editor/) - This editor can open files in Markdown format `.md` and supports **WYSIWYG** editing.
- [**Text Editor**](/extensions/text-editor/) - This editor opens all other text-based file formats, and unknown file types alike. For `.txt` and miscellaneous files, it behaves as a simple editor, with added syntax highlighting capabilities for common programming languages.
- [**JSON Editor**](/extensions/json-editor/) - An interactive visual editor for editing and manipulating `JSON` files.
If the file format of the currently opened files is supported for editing the **EDIT button** will appear in the top right corner of the application. Clicking on this button will activate the edit mode for this file.
Once in edit mode the `Edit` button will disappear and on its place two new buttons will be appear. Pressing the `Cancel` button will revert the changes and exit the edit mode. Pressing the `Save` button will respectively save the changes, which can be done also with the `CMD/CTRL+S` key combination. After saving the changes the file will remain in edit mode and you can continue its editing. If the file is changed you will see a black dot in front of the file extension, visible in the upper left corner of the next screenshot. Saving the changes will make the dot to disappear. The `Cancel` and `Save` button will be exchanged with an`Exit editing` button, which will open the file back with file viewer extension for this file type.
## File revisions
A key feature of document management systems is the ability to create revisions of the edited files. This feature can be enabled in the [Advanced tab](/ui/settings/#advanced) of the application's Settings dialog box. Once activated, a full copy of the current file (e.g. TXT, MD, HTML or JSON) is created with each save. The created file versions are listed in the **Revisions** tab of the file properties view, as seen in the screenshot.
From here, you can **preview** and **restore** previous versions of the file. It is also possible to **delete all** revisions, by clicking the button with the trash bin icon, located in the revision's table header.
### Technical details
The revisions are stored in a subfolder of the `.ts` folder, which is located in the same folder as the file being currently edited. The name of the folder is an unique ID, which is the same as the Entry ID visible in the file properties and saved in the file's sidecar file.
```bash
~ folder1
├ ── .ts
│ ├── 95b6e7d8e00245c7ba8a37d65783d514 - the folder containing the revisions for file4.md
│ │ ├── 1743100950489.md - the version of the files create on the timestamp
│ │ └── 1744314207751.md - another version of the file
│ ├── file4.md.json - contains the entry id for file4 e.g.: 95b6e7d8e00245c7ba8a37d65783d514
│ └── tsm.json - contains tags and description for folder1
└── file4.md
```
## Auto-save changes
The auto-save feature can be enabled individually for each editable file. When it is enabled, the application will save any changes you
make automatically every 40 seconds. In the most editor extensions you can also save the file anytime manually by clicking the save button or by pressing the `CMD/CTRL+S` key combination.
## Increasing your workspace
All of the above editors, will initially open on the right pane of the main area. You can expand your workspace to be able to see and edit more of the document, in two ways:
- **Expand** the editor to fill the whole width of the TagSpaces user interface, by clicking on the **Toggle full width** menu entry, shown in the next screenshot.
- Click on the **Switch to fullscreen** menu entry will open only the area of the editor in full screen mode. To exit fullscreen mode, press the (X) button located at the top right of the screen or just press the **ESC** key on your keyboard.
:::tip
By using the fullscreen feature you are editing the documents in the so called **distraction free mode**. This will expand the editor area to fill the entire screen area, with no window decorations, or other user interface elements, while any applicable **formatting toolbars** and the **Floating Action Button** will still be shown.
:::
---
## 3D Viewer
A TagSpaces extension for opening 3D file formats.
## Features
- 3D preview of GLB, GLTF, STL, and OBJ files
- Rotate the models with mouse dragging
- Use the mouse wheel to zoom in and out
- Hold right-click and move the mouse to shift the rotation center of the model
- Save a screenshot of the current 3D rendering as a PNG file
## Used Libraries
This extension thankfully relies on the following great libraries:
- [model-viewer](https://modelviewer.dev/)
- [viewstl](https://www.viewstl.com/)
- [three.js](https://threejs.org/)
- [FileSaver](https://github.com/eligrey/FileSaver.js/)
- [Bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
## Installation
This extension is pre-installed in TagSpaces Pro.
## License
Proprietary
---
## Archive Viewer
A TagSpaces extension allowing you to preview the content of ZIP files.
## Features
- Listing the content of ZIP files
- Previewing the content of the files in the ZIP container
## Used Libraries
This extension thankfully relies on the following great projects:
- [jszip](https://stuk.github.io/jszip/)
- [Bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
- [DOMPurify](https://github.com/cure53/DOMPurify)
## Installation
This extension is packaged with any new version of TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/archive-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/archive-viewer/LICENSE.txt)
---
## Document Viewer
A TagSpaces extension for previewing document files.
## Features
- Preview files in DOCX format
- Export the content as an HTML file
- Zoom in and out of the content
## Used Libraries
This extension thankfully relies on the following great libraries:
- [mammoth](https://github.com/mwilliamson/mammoth.js/)
- [bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
- [mark.js](https://markjs.io/)
- [dompurify](https://github.com/cure53/DOMPurify)
- [jszip.js](https://stuk.github.io/jszip/)
## Installation
This extension is packaged with any new version of TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/document-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/document-viewer/LICENSE.txt)
---
## eBook Viewer
A TagSpaces extension allowing you to open eBooks or digital magazines in EPUB format.
## Features
- Previewing files in EPUB format
- Automatically switch to two-fold mode by sufficient width
## Used Libraries
This extension thankfully relies on the following great libraries:
- [epub.js](https://github.com/futurepress/epub.js/)
- [Bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
- [jszip.js](https://stuk.github.io/jszip/)
## Installation
This extension is packaged with any new version of TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/ebook-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/ebook-viewer/LICENSE.txt)
---
## Font Viewer
A TagSpaces extension for previewing font files.
## Features
Here is a list of the key features offered by this extension:
- Supporting the following font formats: TTF, OTF, WOFF
- Preview of the font with the standard sentence: _The quick brown fox jumps over the lazy dog_
- Preview of the glyphs in the font file
## Used Libraries
This extension thankfully relies on the following great libraries:
- [Opentype.js](https://opentype.js.org/)
- [Bootstrap](https://getbootstrap.com/)
## Installation
This extension is pre-installed in TagSpaces Pro.
## License
Proprietary
---
## HTML Editor
A TagSpaces extension allowing editing of HTML documents.
## Features
- The standard feature set of the [Summernote](http://summernote.org/) JavaScript library.
- Content cleaning and sanitizing.
- Directly pasting images from the clipboard.
- Saving all the images as data URLs in one HTML file.
## Used Libraries
This extension thankfully relies on the following great libraries:
- [Summernote](http://summernote.org/) - a JavaScript library for HTML editing.
- [Bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
- [Dompurify](https://github.com/cure53/DOMPurify)
## Installation
This extension is packaged with any new version of TagSpaces.
## User Manual
**HTML files** are treated like RichText documents in TagSpaces. When you edit a `.html` document, the fully formatted preview of the file will be replaced by a **WYSIWYG** (**W**hat **Y**ou **S**ee **I**s **W**hat **Y**ou **G**et) HTML editor.
In editor mode, the HTML document will keep its formatting, but you are now able to edit the text, making the HTML editor behave like a RichText editor. On the top of the view, you will find a formatting toolbar, with which you can fully control the appearance of the document.
The formatting toolbar offers some common features you can find in any RichText or WYSIWYG HTML editor, with some features specific to TagSpaces. The overflow menu options from the [HTML viewer](/extensions/html-viewer/) are not implemented in the HTML Editor.
### Toolbar Buttons
The toolbar buttons are grouped together based on similar behavior or functionality. The major groups are illustrated below:
- [**Manage Checkboxes**](#manage-checkboxes) (**1**)
- [**Paragraph Style**](#paragraph-style) (**2**)
- [**Color**](#color) (**3**)
- [**Font Styles**](#font-styles) (**4** and **5**)
- [**Font Family**](#font-family) (**6**)
- [**Lists and Alignment**](#lists-and-alignment) (**7**)
- [**Line Height**](#line-height) (**8**)
- [**Insert Table**](#insert-table) (**9**)
- [**Insert Link, Image and Horizontal Ruler**](#insert-link-image-and-horizontal-ruler) (**10**)
- [**Code View**](#code-view) (**11**)
- [**Help**](#help) (**12**)
#### Manage Checkboxes
This is a compound button, consisting of two parts:
- **Add Checkbox** (**1**)
- **Toggle All Checkboxes** (**2**)
Pressing **Add Checkbox** will insert an interactive, clickable checkbox into your document, which can be used to create, e.g., ToDo lists. To learn more about this feature, scroll down to the [Creating ToDo Lists](#creating-todo-lists) section.
Pressing the **Toggle All Checkboxes** button will select or deselect all the checkboxes present in the HTML document, regardless of their location.
:::tip
When some checkboxes are manually selected, while others are deselected, the **Toggle All Checkboxes** will check all the unchecked ones. Pressing the button again will only uncheck the ones that have been checked via the button. The ones that were manually checked will remain unchanged.
:::
[Back to button group list](#toolbar-buttons)
#### Paragraph Style
This button will open a dropdown menu from which you can select a paragraph style to apply. When selecting an option, the chosen style will be applied to the entire current paragraph (where the cursor is located) without having to make a selection first. If you do select some text first, the style will only be applied to the current selection.
Available styles are:
- **p** represents the `` HTML tag (normal paragraph). It can also be used to remove other styles. The hotkey `Ctrl+0` is assigned to this action.
- **blockquote** will enclose the current paragraph in `
` tags.
- **pre** will enclose the current paragraph in `
` (preformatted text) tags.
- **H1** to **H6** mean different heading levels from **1** (largest) to **6** (smallest). Selecting one of these options will enclose the entire paragraph in `` to `` tags. Hotkeys `Ctrl+1` to `Ctrl+6` can also be used to set headings, where the number reflects the level of the desired heading.
[Back to button group list](#toolbar-buttons)
#### Color
This is a compound button, which has two parts.
The left part, **Recent Color**, will apply the last used background and foreground color on the text. The applicable background and foreground colors are reflected on the button itself.
The right part, **More Color**, will open a dropdown menu, from which you can choose both background and foreground colors to apply, while the default color values can be reset with their respective buttons.
[Back to button group list](#toolbar-buttons)
#### Font Styles
The following groups represent font styles that can be applied to either a selection or as a toggle, to mark any text to be written with the given style, until the toggle is switched off.
**Bold** (**1**), **Italic** (**2**), and **Underline** (**3**) will mark either the selected text or the text that follows as **bold**, _italic_, or underlined, respectively. These three buttons also have hotkeys assigned. `Ctrl+b` will toggle **bold**, `Ctrl+i` toggles _italic_, while `Ctrl+u` toggles underline.
**Superscript** (**4**) and **Subscript** (**5**) will mark either the selection or the text that follows to be superscript or subscript, respectively. **Strikethrough** (**6**) will create ~~strikethrough~~ text, and **Remove Font Style** (**7**) will remove all formatting. (This last option is only applicable to selections.)
From this group, only two options have hotkeys assigned. **Strikethrough** can be toggled with `Ctrl+Shift+s`, while the **Remove Font Style** hotkey is `Ctrl+\`.
[Back to button group list](#toolbar-buttons)
#### Font Family
This is the last of the font style buttons. It can set the selection or the text that follows to a specific font family.
:::tip
The options presented here might depend on your operating system and the fonts installed.
:::
[Back to button group list](#toolbar-buttons)
#### Lists and Alignment
This is a compound group, which offers different options that all work on the currently active paragraph as a toggle, without the need to make a selection first.
The first two buttons offer toggles for **Unordered List** (**1**) and **Ordered List** (**2**). The last button in the group will open a dropdown menu which offers four standard alignment options: **Left** (**3**), **Center** (**4**), **Right** (**5**), and **Full Justify** (**6**); and also the option to **Decrease Indent** (**7**) or **Increase Indent** (**8**).
The hotkeys for these operations are:
- **Unordered List** - `Ctrl+Shift+7`
- **Ordered List** - `Ctrl+Shift+8`
- **Left Align** - `Ctrl+Shift+L`
- **Center Align** - `Ctrl+Shift+E`
- **Right Align** - `Ctrl+Shift+R`
- **Justify Full** - `Ctrl+Shift+J`
- **Decrease Indent** - `Ctrl+Shift+Tab`
- **Increase Indent** - `Ctrl+Tab`
[Back to button group list](#toolbar-buttons)
#### Line Height
Offers a dropdown menu that allows you to set the line-height of either the active paragraph or the currently selected paragraphs between **1.0** and **3.0** by increments of **1.0**, **1.2**, **1.4**, **1.5**, **1.8**, **2.0**, and **3.0**.
:::tip
When you make a selection, you do not need to select the entire paragraph. The selection's edges will mark active paragraphs. The line height adjustment will be performed on all full paragraphs, starting with the one inside which the selection starts, and ending with the one inside which the selection ends.
:::
#### Insert Table
This button will open a drop-down graphical menu for drawing a table grid, with a maximum size of **10x10**, that can be easily inserted into the document.
#### Insert Link, Image, and Horizontal Ruler
This group has the following three buttons:
- [**Insert Link**](#insert-link) (**1**)
- [**Insert Image**](#insert-image) (**2**)
- [**Insert Horizontal Ruler**](#insert-horizontal-ruler) (**3**)
##### Insert Link
The first button will open a dialog that allows you to add a hyperlink to the text. The dialog allows for specifying the text to display and the link to follow when clicked, with a checkbox allowing you to set the link to be opened in a new tab or window. The dialog can also be invoked by pressing `Ctrl+K`.
If you select some text to apply the link to before pressing the button, the selection will automatically populate the _Text to display_ field. If you made no selection, you will need to specify a text to be displayed. If you leave the field empty and start typing a URL, it will automatically populate the text to display field, which you can later modify.
To edit or remove links, you can just click inside the link and use the buttons that appear on the popup.
The first button (**1**) will allow you to edit the link, while the second (**2**) will remove it.
:::tip
Links can also be added to the documents by typing the URL and pressing enter. A well-formed URL will automatically turn into a link.
:::
##### Insert Image
The second button in the group will also open a dialog, which lets you insert a picture from either your computer or from a URL.
##### Insert Horizontal Ruler
The last button will insert a simple horizontal ruler (a HTML `` tag) at the point where the cursor is currently located. The hotkey to quickly insert a horizontal ruler is `Ctrl+Enter`.
:::caution
This button does not respect paragraph endings. If you press this button in the middle of a paragraph, it will break the paragraph at that point.
:::
[Back to button group list](#toolbar-buttons)
#### Code View
This is a toggle to show plain HTML code on a dark background, where the formatting buttons are disabled, and you can edit the HTML code directly.
Pressing the button again will return to the WYSIWYG mode.
:::info
Code highlighting for the HTML view is not currently implemented.
:::
#### Help
The last button will display a summary of all the keybindings. If you prefer to use hotkeys, you will find a quick reference here.
### Creating ToDo Lists
The recently added feature of interactive checkboxes makes TagSpaces ideal for creating simple, yet flexible **ToDo lists**. Pressing the [**Add Checkbox Button**](#add-checkbox) button will insert a checkbox anywhere in the text.
For **ToDo Lists**, you would ideally want the checkbox to be the very first character of a list, although you are not limited by placement. To make your list multi-level (i.e. sub-items under list items), you can use the **Increase Indent** feature (see [Toolbar Buttons -> Lists and Alignment](#lists-and-alignment)) on the desired line, by either pressing its button or using its hotkey (`Ctrl+Tab` to increase indent, `Ctrl+Shift+Tab` to decrease indent).
:::tip
The interactive checkboxes only work in editor mode. When in HTML preview mode, you can see the current state of the box, but cannot change it. To make a list interactive, switch to editor mode by pressing the little pencil icon at the top of the preview.
:::
### Key bindings
Below you can find a summary of all the hotkeys you can use in the HTML Editor
:::tip
Mac users should use the `Cmd` key, where `Ctrl` is mentioned
:::
- `Ctrl+Z` - Undo the last command
- `Ctrl+Y` - Redo the last command
- `Tab` - Insert Tab
- `Shift+Tab` - Remove tab
- `Ctrl+B` - Set a bold style
- `Ctrl+I` - Set an italic style
- `Ctrl+U` - Set an underline style
- `Ctrl+Shift+S` - Set a strikethrough style
- `Ctrl+\` - Clear all styles
- `Ctrl+Shift+L` - Set left align
- `Ctrl+Shift+E` - Set center align
- `Ctrl+Shift+R` - Set right align
- `Ctrl+Shift+J` - Set full align
- `Ctrl+Shift+7` - Toggle unordered list
- `Ctrl+Shift+8` - Toggle ordered list
- `Ctrl+Tab` - Indent on current paragraph
- `Ctrl+Shift+Tab` - Outdent on current paragraph
- `Ctrl+0` - Change current paragraph's style to plain paragraph (`` tag)
- `Ctrl+1` - Change current paragraph's style to H1
- `Ctrl+2` - Change current paragraph's style to H2
- `Ctrl+3` - Change current paragraph's style to H3
- `Ctrl+4` - Change current paragraph's style to H4
- `Ctrl+5` - Change current paragraph's style to H5
- `Ctrl+6` - Change current paragraph's style to H6
- `Ctrl+Enter` - Insert horizontal rule
- `Ctrl+K` - Show Link Dialog
## Source code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/html-editor).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspa ces/tagspaces-extensions/blob/main/html-editor/LICENSE.txt)
---
## HTML Viewer
A TagSpaces extension allowing opening of HTML files.
## Features
Here is a list of the key features offered by this extension:
- Zoom in and zoom out capabilities
- Printing the document
- Search for text in the current document
- Reader mode, extracting only the main part of the document by stripping header, footer, and navigation if available
### Meta-Data
The TagSpaces [Firefox](https://addons.mozilla.org/en-us/firefox/addon/tagspaces/) and [Chrome](https://chrome.google.com/webstore/detail/tagspaces/ldalmgifdlgpiiadeccbcjojljeanhjk) web clippers save the date and time of the saving, the URL from which the webpage is saved, and optionally a screenshot. This information can be accessed from the `File Details` menu entry in the extension's main menu. In the dialog that will appear, you will see the screenshot of the web page (if available) and the original URL of the webpage.
## Used Libraries
This extension thankfully relies on the following great libraries:
- [Readability](https://github.com/mozilla/readability)
- [Bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
- [DOMPurify](https://github.com/cure53/DOMPurify)
## Installation
This extension is packaged with any new version of TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/html-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/html-viewer/LICENSE.txt)
---
## Image Viewer
A TagSpaces extension allowing you to open different kinds of image formats.
## Features
- Opening of the following image formats: JPG, PNG, GIF, SVG, BMP, WEBP, ICO, TIFF, AVIF, TGA
- Preview of these formats: CR2, NEF, DNG, PSD
- Zooming, flipping, and rotating of the current image
- Different background colors of the viewer for better contrast
- For JPG files, it features an integrated Exif and IPTC reader with auto-rotation of photos according to the Exif information
- Support for image printing
- Grayscale filter
- Exporting the current image in JPG, PNG, or WEBP format (only for the desktop apps)
The following screenshot shows a dialog with the extracted Exif and IPTC information.
## Used Libraries
This extension thankfully relies on the following great libraries:
- [viewer.js](https://fengyuanchen.github.io/viewerjs/)
- [exif.js](https://github.com/exif-js/exif-js)
- [UTIF.js](https://github.com/photopea/UTIF.js/)
- [tga.js](https://github.com/vthibault/tga.js/)
- [psd](https://github.com/meltingice/psd.js/)
- [Bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
## Installation
This extension is packaged with any new version of TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/image-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/image-viewer/LICENSE.txt)
---
## JSON Editor
A TagSpaces extension allowing viewing and editing of JSON documents.
## Features
- Open and edit JSON documents graphically.
## Used Libraries
This extension thankfully relies on the following great libraries:
- [JSON editor](https://github.com/josdejong/jsoneditor)
- [Bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
- [Mark.js](https://markjs.io/)
## Installation
This extension is packaged with any new version of TagSpaces.
## User Manual
Editing JSON files will build upon the functionality you've already seen in the **JSON Preview mode**.
The top row of the editor will offer a basic toolbar, with some common actions such as **Expand all fields** (**1**), **Collapse all fields** (**2**), **Undo** and **Redo** (**3**), and a search box (**4**).
Each field has some useful controls that can help manipulate and rearrange JSON files easily.
- On the left edge, there is a drag handle, allowing for easy movement of each row (**1**).
- Next to the drag handle is an **Action Menu Button** (**2**), which opens the **Action Menu** (**3**), offering useful actions on each field, such as:
- You can choose or change the **Type** of the field, choosing from _Auto_, _Object_, _Array_, or _String_.
- You can **Insert** an _Array_, _Object_, or _String_ inside any field (there is also an _Auto_ mode for insertion). Inserting will place the new field **before** the selected field.
- When selecting the **Action Menu** on the last member of an _Object_ or _Array_, you can also **Append** the same categories, which will place the new field **after** the last item.
- _Objects_ and _Arrays_ will also allow for **Sorting**, either _Ascending_ or _Descending_.
- Finally, you can **Duplicate** or **Remove** any field from the hierarchy (apart from the root).
- To the right of the Action Menu Button, there is an **Open/Close Chevron** (**4**), which can expand or collapse each field.
- Finally, you have the field itself, with one (**5**) (for arrays and objects) or two editable sections (**6**) (for string type), and an optional, read-only information field (**7**) that displays the number of sub-fields, in either curly brackets `{ }` (for objects) or square brackets `[ ]` (for arrays).
The **FAB Overflow Menu** will offer to either **Print** the file or display a **JSON Help** menu, which gives a summary of the numerous key combinations that can be used to work on JSON files even faster.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/json-editor).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/json-editor/LICENSE.txt)
---
## Markdown Editor
A TagSpaces extension allowing viewing and editing of Markdown files.
## Features
- **WYSIWYG** Markdown editing
- Embedding images, also as data URLs
- Support for emojis 🍒
- Support for tables
- Simple text _formatting_ and headers
- Copy and paste markdown text
- Support for math expressions
- Reading aloud the text content of the document
- Visualizing the markdown header structure as a mind map
**TIP**: Just type `/` on a new line to get a menu showing all available markdown elements such as headings, bullet lists, images, quotes or tables.
### Mindmap
The extension can generate a mind map structure of the document based on its header structure.
### Diagrams (depracated)
The editor supports presenting and editing of [mermaid](https://mermaid-js.github.io/mermaid/) based diagrams:
## Live Demo
You can test it live [here](https://demo.tagspaces.com/int.html?tslid=10ades09-c7fd-zt33-fc67-a75db43rt4gz&tsdpath=demo%2FNote-Taking&tsepath=demo%2FNote-Taking%2Fcomplex-markdown-note.md).
## Used Libraries
This extension thankfully relies on the following libraries:
- [Milkdown](https://milkdown.dev/)
- [React](https://reactjs.org/)
- [Mui](https://mui.com/)
## Keyboard Shortcuts
> `Mod` is `Cmd` on macOS and `Ctrl` for Windows/Linux.
### Essentials
| Action | Key |
| --------- | --------- |
| Copy | Mod-c |
| Cut | Mod-x |
| Paste | Mod-v |
| New Line | Enter |
| Exit Code | Mod-Enter |
| Print | Mod-p |
| Save | Mod-s |
### History
| Action | Key |
| ------ | ----------- |
| Undo | Mod-z |
| Redo | Mod-Shift-z |
### Mark
| Action | Key |
| -------------- | --------- |
| Bold | Mod-b |
| Italic | Mod-i |
| Inline Code | Mod-e |
| Strike Through | Mod-Alt-x |
### Paragraph
| Action | Key |
| ----------- | ----------- |
| Normal Text | Mod-Alt-0 |
| H1 | Mod-Alt-1 |
| H2 | Mod-Alt-2 |
| H3 | Mod-Alt-3 |
| H4 | Mod-Alt-4 |
| H5 | Mod-Alt-5 |
| H6 | Mod-Alt-6 |
| Code Fence | Mod-Alt-c |
| Line Break | Shift-Enter |
### List
| Action | Key |
| -------------- | --------- |
| Ordered List | Mod-Alt-7 |
| Bullet List | Mod-Alt-8 |
| Task List | Mod-Alt-9 |
| Sink List Item | Mod-] |
| Lift List Item | Mod-[ |
### Table
| Action | Key |
| -------------------- | --------- |
| Next Cell | Mod-] |
| Prev Cell | Mod-[ |
| Exit Table and Break | Mod-Enter |
---
## Installation
This extension is packaged with any new version of TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/md-editor).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/md-editor/LICENSE.txt)
---
## Markdown Viewer
A TagSpaces extension that allows for the opening of markdown files.
## Features
- Offers different themes for displaying documents.
- Find text in the current document.
- Export the content as an HTML file.
- Zoom in and out of the content.
- Document printing.
## Used Libraries
This extension relies on the following great projects:
- [marked](https://github.com/chjj/marked) - A markdown parser and compiler.
- [Bootstrap](https://getbootstrap.com/) - A popular CSS framework for responsive design.
- [i18next](https://www.i18next.com/) - An internationalization framework for JavaScript.
- [Mark.js](https://markjs.io/) - A library to highlight text in a document.
- [Dompurify](https://github.com/cure53/DOMPurify) - A DOM-only XSS sanitizer.
## Installation
This extension is packaged with any new version of TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/md-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/md-viewer/LICENSE.txt)
---
## Media Player
A TagSpaces extension that allows the playback of audio and video files.
## Features
- Play audio and video files.
- Fullscreen mode for an immersive experience.
- Automatically triggers the opening of the next file in the current folder upon finishing playback, allowing you to listen to multiple audio files continuously, just like a regular music player.
:::info
The supported audio and video formats depend on the underlying browser platform.
:::
## Used Libraries
This extension relies on the following excellent libraries:
- [Vidstack](https://vidstack.io/) - An advanced, customizable HTML5 media player.
- [React](https://reactjs.org/) - A JavaScript library for building user interfaces.
- [Mui](https://mui.com/) - A popular React UI framework.
## Installation
This extension is packaged with any new version of TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/media-player).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/media-player/LICENSE.txt)
---
## MHTML Viewer
A TagSpaces extension allowing you to open MHTML and EML files.
## Features
- Viewing of MHTML/MHT files - MHTML is a [file format](https://tools.ietf.org/html/rfc2557) for saving web pages with all the images and styling information in one single file. Saving in MHTML format is natively supported by [Chrome™](/web-clipper#enabling-the-saving-of-webpages-as-mhtml) and Internet Explorer™ browsers.
- Viewing of EML files - EML is a file format for saving emails. It is the default email export format of email apps such as Thunderbird™ or Google Mail™.
- Reader mode, extracting only the main part of the document by stripping header, footer, and navigation if available.
- Showing the creation date of the file.
- Opening the source URL of an MHTML file.
- Finding text in the current file.
- File printing.
Dialog showing the scraping details, with the ability to open the original URL in an external browser.
### Showing email exported in EML format
## Used Libraries
This extension thankfully relies on the following great projects:
- [mailparser](https://github.com/andris9/mailparser) - A powerful library for parsing email messages.
- [Readability](https://github.com/mozilla/readability) - A library that extracts the main content of web pages.
- [Bootstrap](https://getbootstrap.com/) - A popular CSS framework for responsive design.
- [i18next](https://www.i18next.com/) - An internationalization framework for JavaScript.
- [Mark.js](https://markjs.io/) - A library to highlight text in a document.
- [Dompurify](https://github.com/cure53/DOMPurify) - A DOM-only XSS sanitizer.
## Installation
This extension is packaged with any new version of TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/mhtml-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/mhtml-viewer/LICENSE.txt)
---
## Mindmap Viewer
A TagSpaces extension for opening mind maps based on markdown with the help of markmap.js.
## Features
- Preview mind maps
- Zoom in and out with the mouse wheel and menu
## Used Libraries
This extension thankfully relies on the following great libraries:
- [markmap.js](https://markmap.js.org/)
- [Bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
- [Dompurify](https://github.com/cure53/DOMPurify)
## Installation
This extension is packaged with the new version of TagSpaces (after version 5.2).
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/mindmap-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/mindmap-viewer/LICENSE.txt)
---
## MSG Viewer
A TagSpaces extension allowing you to open email in MSG format.
## Features
- Opens emails in MSG format.
- Export the content as HTML file.
- Zoom in and out of the content.
## Used Libraries
This extension thankfully relies on the following libraries:
- [msg.reader](https://github.com/ykarpovich/msg.reader)
- [Bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
- [Mark.js](https://markjs.io/)
- [Dompurify](https://github.com/cure53/DOMPurify)
## Installation
This extension is packaged with any new version of TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/msg-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/msg-viewer/LICENSE.txt)
---
## PDF Viewer
A TagSpaces extension allowing opening, searching, and navigating through PDF files.
## Features
- Adding text and drawings on the document's pages.
- Highlighting text and areas.
- Rotating and zooming of pages.
- Showing preview of the pages.
- Showing table of contents.
- Finding text in PDF documents.
- Printing PDF documents.
:::caution
In order to save the annotations (text or drawing), you have to download the PDF document from the icon in the toolbar. Otherwise, by closing or changing the document, your changes will be lost.
:::
## Used Libraries
This extension thankfully relies on the following great projects:
- [PDF.js](https://mozilla.github.io/pdf.js/)
- [Bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
## Installation
This extension is packaged with any new version of TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/pdf-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/pdf-viewer/LICENSE.txt)
---
## RTF Viewer
A TagSpaces extension allowing the opening of RTF files.
## Features
- Preview files in RTF format.
- Export the content as an HTML file.
- Zoom in and out of the content.
## Used Libraries
This extension thankfully relies on the following great libraries:
- [rtf.js](https://github.com/tbluemel/rtf.js)
- [Bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
- [Mark.js](https://markjs.io/)
- [Dompurify](https://github.com/cure53/DOMPurify)
## Installation
This extension is packaged by default with TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/rtf-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/rtf-viewer/LICENSE.txt)
---
## Slides Viewer
A TagSpaces extension for opening slides in HTML format created with reveal.js. The extension is introduced for the first time in version 5.2.3 of TagSpaces.
## Features
- Preview reveal.js slides
:::note
The extension extracts only the content of the reveal.js presentation from the HTML file and removes all the embedded and referenced JavaScript code. For the rendering of the slides, it relies on the embedded reveal.js library. This is done to reduce the risk of opening malicious HTML files. The drawback is that the reveal.js version may be outdated and not support the newest features of the latest release.
:::
## Used Libraries
This extension thankfully relies on the following great libraries:
- [reveal.js](https://revealjs.com/)
## Installation
This extension is packaged with the new version of TagSpaces (after version 5.2).
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/slides-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/slides-viewer/LICENSE.txt)
---
## Spreadsheet Viewer
A TagSpaces extension allowing you to preview the content of spreadsheet files.
## Features
- Previewing the content of the XLSX files with sheets
- Previewing the content of the ODS files with sheets
- Previewing the content of the CSV files
- Export the content as an HTML file
- Zoom in and out of the content
## Used Libraries
This extension thankfully relies on the following great projects:
- [SheetJS](https://sheetjs.com/)
- [Bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
- [Mark.js](https://markjs.io/)
- [Dompurify](https://github.com/cure53/DOMPurify)
## Installation
This extension is packaged with any new version of TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/spreadsheet-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/spreadsheet-viewer/LICENSE.txt)
---
## Text Editor
A TagSpaces extension allowing editing of text-based documents.
## Features
- Opening and editing of text documents
- Syntax highlighting for the following file types: h, c, clj, coffee, coldfusion, cpp, cs, css, groovy, haxe, htm, html, java, js, ts, tsx, jsm, json, latex, less, ly, ily, lua, markdown, md, mdx, ml, mli, pl, php, powershell, py, rb, scad, scala, scss, sh, sql, svg, textile, txt, xml
## Used Libraries
This extension thankfully relies on the following great libraries:
- [Monaco-editor](https://microsoft.github.io/monaco-editor/)
- [React](https://reactjs.org/) - A JavaScript library for building user interfaces.
- [Mui](https://mui.com/material-ui/) - A popular React UI framework.
- [i18next](https://www.i18next.com/)
- [Dompurify](https://github.com/cure53/DOMPurify) - library for content sanitization
## Installation
This extension is packaged with any new version of TagSpaces.
## User Manual
### Text Editor
The text editor offers code highlighting for some common programming languages. In the extension menu you will find some extras like toggling line number, adjusting the font size or toggling the wrapping for words.
The text editor will keep the option to print from the plain [text viewer](/extensions/text-viewer/).
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/text-editor).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/text-editor/LICENSE.txt)
---
## Text Viewer
A TagSpaces extension allowing you to preview any kind of files as text.
## Features
- Displaying the content of files as plain text.
## Used Libraries
This extension relies on the following libraries:
- [Bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
- [Mark.js](https://markjs.io/)
- [Dompurify](https://github.com/cure53/DOMPurify)
## Installation
This extension is packaged with any new version of TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/text-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/text-viewer/LICENSE.txt)
---
## URL Viewer
A TagSpaces extension allowing you to open URL files created from web browsers or bookmark managers.
## Features
- Enables TagSpaces to be used as a bookmark management application.
- Opening links from Ubuntu's `.desktop` files, created, for example, by dragging URLs from the Chrome browser.
- Opening links from Windows' `.url` files, created, for example, by the Favorite Manager of Internet Explorer.
- Opening links from Ubuntu's `.website` files.
- With this extension, it is possible to use TagSpaces as a bookmark manager with support for tagging.
## Used Libraries
This extension thankfully relies on the following libraries:
- [Bootstrap](https://getbootstrap.com/)
- [i18next](https://www.i18next.com/)
- [Dompurify](https://github.com/cure53/DOMPurify)
## Installation
This extension is packaged with any new version of TagSpaces.
## Source Code
The source code of this extension is freely available on [GitHub](https://github.com/tagspaces/tagspaces-extensions/tree/main/url-viewer).
## Development
If you want to extend this extension, please follow our general [extension development guide](/dev/extension-development-guide).
## License
[MIT](https://github.com/tagspaces/tagspaces-extensions/blob/main/url-viewer/LICENSE.txt)
---
## Files Overview
## File Areas
The in top area of a file you can switch between the following sub-areas:
- **[Details](#file-properties)** - opens the file properties, see more bellow.
- **[Description](#file-description)** - opens the area where you can add description for this file (opened in the screenshot bellow).
- **[Revisions](/editing-files/#file-revisions)** - visible only for editable files, display a list of all file changes.
- **[Links](/linking)** - a place where you can see all incoming and outgoing links for this file.
:::tip
Click on the tab of the currently opened area will close it, making more space for the file preview or file editing area respectively.
:::
## File Menu
The file preview toolbar offers several actions, some of which are described below:
- **(1) Reload** - Reloads the properties of the file in the file preview area.
- **(2) Download file** - If the file is on a s3 object storage, this button will start downloading process. On local files, the button will open a file save dialog, allowing you to make a copy of the file on your file system.
- **(3) Switch to fullscreen** - Opens the file preview in full screen. You can exit full-screen mode by clicking the `ESC` key on your keyboard or by clicking the round green X-button in the top-right corner of the screen.
- **(4) Toggle full width** - Toggles the file preview to full width by hiding the file browsing areas in the left panel of the app.
- **(5) Delete** - Opens a dialog where you can confirm the deletion of the file.
- **(6) Navigate to parent folder** - Opens the parent folder of the file in the main area of the application.
- **(7) Open in new window** - Opens the file in a new TagSpaces window or tab in the web version.
- **(8) Open file natively** - Opens the current file in the default application of your operating system.
- **(9) Close entry** - Will close the file properties area.
## File Properties
Clicking the **( i )** icon button will open and close the file properties area. Here, you will find details about the currently opened file such as:
- **(1) File Name** - Shows the complete name of the file, including its extension. Clicking the `Rename` button or just on the file name will allow you to change it.
- **(2) Tags** - Displays the tags added to the file. Clicking on this area will open a dropdown where you can select additional tags to assign to the file. You can also drop tags from the tag library or other files or folders here.
- **(3) Map with geo-tag** - If the file has an attached [geo-tag](/ui/taglibrary#geo-tagging), a map will be displayed, showing the exact location of the geo-tag. The map server used is configurable in the [settings](/ui/settings/#advanced) of the app.
- **(4) Date Modified** - Shows the date and time when the file was last modified.
- **(5) Size** - Displays the size of the current file.
- **(6) Path** - Shows the complete path of the file. If the file is located on an object storage location, a cloud icon instead of a suitcase will appear in front of the path. Clicking the `Move` button will open a dialog allowing you to move or copy the file to another folder.
- **(7) Sharing link** - Displays a link for [internal sharing](/sharing#internal-sharing-for-files-and-folders). Clicking `Copy` will copy the link to the clipboard so that you can share the file with other users or TagSpaces installations.
- **(8) Link for downloading** - The `Generate link` button will open a dialog where you can generate a [link or QR-code](/sharing#sharing-download-link-to-a-file) for downloading the file. This section is visible only for files located on S3 storage.
- **(9) Thumbnail** - Displays the current thumbnail of the file. Clicking `Change` will open a dialog where you can choose a new thumbnail. The application supports adding a custom thumbnail to any file type.
- **(10) [Entry ID](/linking)** - the file identifier used for internal TagSpaces links.
## File Description
TagSpaces PRO allows users to add descriptions to any kind of files.
:::tip
Typing the forward slash `/` will open the context menu visible in the previous screenshot, with which you can insert various text elements supported in the description editor. Pressing `cmd + s` on Mac or `command + s` Windows or Linux PCs will save the changes in the descirptions
:::
## File Thumbnails
TagSpaces can automatically generate thumbnails for many file types, as described [here](/thumbnails). Additionally, the PRO version offers a dialog where you can set a custom thumbnail for any file type, even those unsupported by the automatic [thumbnail generation](/thumbnails).
:::tip
An image in the clipboard can be used as thumbnail after pasting it in this dialog with `cmd/ctrl+v`
:::
:::info
If the file is on an S3 object storage, the thumbnail will be uploaded there.
:::
## Technical details
The description and tags are added in a [sidecar file](/dev/metafileformats#file-meta-description-format) located in the hidden `.ts` folder within the current folder. This file has the same name as the original file with additional `.json` at the end.
The `.ts` folder contains also the thumbnail images of the files. The thumbnail files have also the same name as original file but with `.jpg` at the end.
For some file format like PDF, the `.ts` folder can have a sidecar file containing the text content of the original file. This files has the same name as original file with additional `.txt` at the end. These files are used for speeding-up the search and for some AI functionalities.
```
~ some-folder
├── .ts
│ ├── file5.png.json - contains tags and description for file.png
│ ├── file5.png.jpg - is the thumbnail image for file5.png
│ ├── file6.pdf.json - contains tags and description for file6.pdf
│ ├── file6.pdf.txt - contains the extracted text content of file6.pdf
│ ├── file6.pdf.jpg - is the thumbnail image for file6.pdf
│ └── tsm.json
├── file5.png
└── file6.pdf
```
---
## Folders Overview
Folders play an essential role in TagSpaces that goes beyond typical file grouping and organization. We have enhanced their functionality by adding tagging, description, custom background, thumbnail, wallpaper, and a default perspective. This allows you to turn every folder into a so-called **file-based app**, depending on the files stored within it.
## Folder Areas
The in top area of a folder you can switch between the following sub-areas:
- **[Details](#folder-properties)** - opens the folder properties, see more bellow.
- **[Description](#folder-description)** - opens the area where you can add description for this folder (opened in the screenshot bellow).
- **[AI Chat](/ai#ai-chat-in-folders)** - this is the place for the folder's own AI chat, this tab is visible only if the AI functionality is enabled.
- **[Links](/linking)** - a place where you can see all incoming and outgoing links for this folder.
## Folder Menu
The toolbar for folders can be seen in the following screenshot:
The following actions can be accessed from the toolbar:
- **(1) Reload folder** - Reloads the folder properties.
- **(2) Open in main area** - Opens the folder in the main area of the application. This is useful if you have navigated away from the folder opened in the preview area.
- **(3) Open in new window** - Opens the folder in a new window or tab in the web version.
- **(4) Open folder externally** - Opens the folder in the default file manager of your operating system, not available for S3 locations.
- **(5) Toggle full width** - Opens the folder properties in full width, giving more space for AI tasks, writing description.
- **(6) Delete folder** - Starts the process for deleting the current folder along with its files and subfolders.
- **(7) Close entry** - Closes the folder properties area.
## Folder Properties
The folder properties section is similar to the file properties area.
- **(1) Folder Name** - Displays the complete folder name. Clicking the **RENAME** button will make the name editable.
- **(2) [Tags](/tagging#folder-tagging)** - Displays the folder's tags. Clicking on this area opens a dropdown to assign additional tags, or you can drag and drop tags from the tag library or other files and folders.
- **(3) Map with geo-tag** - If geo-tagged, a map with a droppin shows the exact [geo tag](/ui/taglibrary/#geo-tagging). The map tile server is configurable in the [settings](/ui/settings/#advanced).
- **(4) [Description](#folder-description)** - Displays the folder description. Opening this tab will allow you to add description for the folder.
- **(5) Date modified** - Shows the last modified date and time of the folder.
- **(6) Size** - Displays the calculated size of the folder, including subfolders. This feature is unavailable on object storage locations.
- **(7) Path** - Shows the complete folder path. For object storage locations, a cloud icon is shown instead of a suitcase. Clicking **MOVE** opens a dialog to move or copy the folder.
- **(8) Sharing link** - Shows the internal sharing [link](/sharing#internal-sharing-for-files-and-folders). Clicking **COPY** copies the link to your clipboard for sharing with others or other TagSpaces installations.
- **(9) [Default folder perspective](#default-folder-perspective)** - Lets you specify the default perspective for this folder.
- **(10) [Background color](#folder-background)** - Displays the folder's background color. Clicking the color area opens a dialog to change the folder's color.
- **(11) [Thumbnail](#folder-thumbnail)** - Displays the folder's current thumbnail. Clicking **CHANGE** opens a dialog to select a new thumbnail.
- **(12) [Background Image](#folder-wallpaper)** - Shows a preview of the folder's wallpaper. Clicking **CHANGE** allows you to choose a new wallpaper.
- **(13) [Entry ID](/linking)** - the folder identifier used for internal TagSpaces links.
## Folder Description
Folders can be annotated with descriptions, useful for adding additional information to files or folders. Descriptions are managed in the a separate tab in the folder' properties area.
The folder descriptions can be edited by clicking the **EDIT** button or by double-clicking directly in the description area. The description text can contain [Markdown](https://en.wikipedia.org/wiki/Markdown), allowing you to add basic formatting, [links](/linking), and lists to the content.
The descriptions are indexed by the search algorithm and considered in search results. If a given file or folder has a description, the first few words from it are displayed in the grid perspective.
## Default Folder Perspective
Every folder can have its own default perspective, which can be selected in the folder properties area.
Once you choose a perspective, every time you open this folder, it should open with the selected perspective.
## Folder Background
With this feature, every folder in TagSpaces can have its own background color or gradient. In addition to tagging, you can use colors to mark folders for particular use cases or areas of work. For example, you can differentiate your personal folders from your work folders using color or mark folders containing sensitive or important information.
In the previous screenshot, you can see a preview **(1)** of the background color. Clicking the preview will open the dialog shown in the screenshot. **(2)** switches between editing a color or a color gradient. **(3)** shows a set of 4 predefined backgrounds, and with button **(4)**, the background can be cleared.
The folder background is visible in grid, list, gallery, and kanban perspectives, even when the folder is shown as a subfolder.
## Folder Thumbnail
In TagSpaces Pro, users can manually set a thumbnail for any file or folder. This can be achieved in a dedicated dialog, where you can choose an image from your hard drive or from thumbnails embedded in the application. The images used here are based on the [illlustrations.co](https://illlustrations.co) kit. In this dialog, you can also clear the folder's thumbnail.
:::info
If the folder is on an S3 bucket, the selected thumbnail file will be uploaded there.
:::
:::tip
An image in the clipboard can be used as thumbnail after pasting it in this dialog with `cmd/ctrl+v`
:::
Adding a custom thumbnail to any file type can be achieved similarly from the file's properties section.
## Folder Background Image
Folders can have background images (wallpapers) in TagSpaces Pro. The background images are supported in the Grid, List, Gallery and Kanban [perspectives](/browsing-files).
The background image can be changed in the folder properties, where you can open the dialog for changing the wallpapers.
:::tip
An image in the clipboard can be used as background for a folder after pasting it in this dialog with `cmd/ctrl+v`
:::
Some wallpapers are bundled with the application, but you can also choose an image from your hard drive. In the dialog, you also can also clear any previously selected wallpapers.
:::info
If the folder is on an S3 bucket, the wallpaper file will be uploaded there.
:::
## Technical details
The folder descriptions, id, background color, preferred perspective and tags are saved in a [sidecar file](/dev/metafileformats#folder-meta-description-format) called `tsm.json` within the hidden `.ts` folder of the current folder.
The `.ts` folder contains also the thumbnail images of the files. The thumbnail files have also the same name as original file but with `.jpg` at the end.
```bash
~ folder1
├── sub-folder2
│ └── .ts
│ └── tsm.json - can contains tags and description for sub-folder2
├── .ts
│ ├── file4.docx.json - can contain tags and description for file4.docx
│ ├── tsb.jpg - is the background image for the folder1
│ ├── tst.jpg - is the thumbnail image of the folder1
│ └── tsm.json - contains tags and description for some-folder1
└── file4.docx
```
---
## Installing TagSpaces
Here you will learn how to install TagSpaces on different operating systems.
## Getting the Application
The free versions of TagSpaces are available for download from the [Downloads Section](https://www.tagspaces.org/downloads/) on the TagSpaces website. Here, you can quickly find the appropriate installer for your operating system (Windows, macOS, Linux, Android, Firefox, and Chrome).
:::tip
**Download the newest PRO release:** TagSpaces PRO customers should use the download links provided in their purchase confirmation email. These links will always point to the latest available PRO version.
:::
### New Version Notification
When a new version of the application is available, you will see a notification in the lower-left corner of the app. Clicking the **Get It Now** button will direct you to the TagSpaces website download page, where you can obtain the latest community version. **TagSpaces Pro** users should use the links in their order confirmation email to access the latest version or follow this [link](https://tagspacesstore.onfastspring.com/account).
:::tip
If you prefer not to have TagSpaces check automatically for new versions, you can disable this functionality in the [settings](/ui/settings).
:::
## Installation on Windows
The Windows version of TagSpaces is distributed as either an `.exe` installer or a `.zip` archive file. The `.exe` file can be directly executed to start the installation. The `.zip` archive must be unzipped into a folder on your system. In the unpacked folder, you will find a file named `tagspaces.exe`, which can be executed with a double-click.
The installer is signed with modern software certificates, ensuring authenticity. By a right click on installer and choosing **Properties**, you can check the certificate of the installer, see the screenshot for orientation.
:::tip
The **profile** folder under Windows is located here: `C:\Users\Your_User_Name\AppData\Roaming\TagSpaces`
:::
### Updating the Windows version
To update, replace the contents of your current installation with the contents from the zip file of a newer release. Your tag library and locations are stored in the user's home folder, so you won’t lose any data during the update process.
## Installation on macOS
For macOS, you can [download](https://www.tagspaces.org/downloads/) the 64-bit versions of TagSpaces for either Intel or Apple Silicon (ARM) processors. After downloading, double-click the zip file in Finder to properly unpack it. Some users have reported issues unpacking the app with third-party zip utilities, so it’s recommended to use Finder.
:::tip
The **profile** folder under macOS is located here: `~/Library/Application Support/TagSpaces`
:::
### Updating the macOS version
To update, replace the contents of your current installation with the files from the zip archive of the new release. Your tag library and locations are stored in the user's home folder, ensuring no data loss during updates.
## Installation on Linux
The Linux version of TagSpaces is available as a `tar.gz` archive, an `AppImage`, and a `.deb` file for Debian-based distributions like Ubuntu. All versions are available for download [here](https://www.tagspaces.org/downloads/).
To install:
- For the `tar.gz` file, unpack it into a folder on your system. In the unpacked folder, you’ll find a `tagspaces` executable, which can be run with a double-click or via terminal.
- For the `.deb` package, double-click to install or use the following command:
```bash
sudo dpkg -i tagspaces-linux-amd64-x.x.x.deb
```
For the AppImage, make it executable first:
```bash
chmod +x tagspaces-linux-x86_64-x.x.x.AppImage
```
Then, you can launch it with a double-click.
:::tip
The **profile** folder under Linux/Ubuntu is located here: `~/.config/TagSpaces`
:::
### Updating the Linux version
To update the **tar.gz** version, replace the contents of your current installation with the files from the new release. Your tag library and locations are persisted in the user's home folder. For distribution packages, simply reinstall over the current version.
## Installation on Android
:::caution
The Android version is meanwhile **deprecated**, we still are still releasing new versions, but we are not actively developing the app anymore.
:::
A version of the Android app is available as an [APK file](https://www.tagspaces.org/downloads/) in the download section of our website.
To install the APK file, follow these steps on your Android phone:
1. Go to **Settings**.
2. Open the **Security & privacy** option.
3. Scroll down and find **Install from unknown apps**. If it’s not there, try looking under **More**.
4. You should see a list of apps. Find your browser (e.g., Firefox or Chrome).
5. Tap on your browser and choose **Allow from this source**.
If the above steps do not work, try the following:
1. Go to **Settings**.
2. Open **Apps & Notifications** and select **Configure apps**.
3. Scroll down and tap on **Advanced options** or **Special app access**.
4. Scroll to the bottom and find the **Install unknown apps** option.
5. Select your browser, tap on it, and enable **Allow from this source**.
Once these steps are done, download and install the APK from our [download section](https://www.tagspaces.org/downloads) using your configured browser.
:::caution
**Risks of installing apps outside the Play Store:** Installing apps from outside the Google Play Store can expose your phone to potential security risks, including viruses. Always ensure you are downloading from trusted sources.
:::
## Installing the Firefox Browser Extension
Download the [TagSpaces Add-on for Firefox](https://addons.mozilla.org/en-us/firefox/addon/tagspaces/). Open the **Add-ons tab** in Firefox from the main menu by clicking on the puzzle icon, or simply type `Ctrl+Shift+A` (or `Command+Shift+A` on macOS). In the new tab, go to the settings dropdown next to the search bar and select **Install Add-on From File...**. Choose the downloaded file and follow the instructions.
Once installed, you can start the add-on from the TagSpaces icon in the top-right corner of your browser or through **Tools > TagSpaces** in the main menu.
> **Updating the Firefox Add-on:** Once a newer version of the Firefox add-on is approved by Mozilla, it will automatically be installed on your Firefox browser.
## Installing the Chrome Browser Extension
You can install the Chrome extension directly from the [Chrome Web Store](https://chrome.google.com/webstore/detail/tagspaces-web-clipper/ldalmgifdlgpiiadeccbcjojljeanhjk).
> **Updating the Chrome Extension:** Once a new version of the Chrome extension is published on the Chrome Web Store, it will be automatically installed on your Chrome browser.
## Running in Portable Mode
The Windows, macOS and Linux versions of TagSpaces can run in "portable mode," allowing you to use the application from a USB stick or other portable devices. In this mode, all configuration data (such as tags, tag groups, and location connections) is stored in a folder called `tsprofile` within the same directory where the application is started, rather than in the home directory of the operating system.
### On Windows and Linux
To start the portable mode, use the `tagspacesp.cmd` script on Windows or `tagspacesp` on Linux. These scripts are usually found in the unpacked application folder. On Linux, you may need to make the script executable by running:
```bash
chmod +x tagspacesp
```
If the files are not included in the distributed packages, they can be downloaded from the following locations:
- [tagspacesp (Linux)](https://raw.githubusercontent.com/tagspaces/tagspaces/develop/resources/tagspacesp)
- [tagspacesp.cmd (Windows)](https://raw.githubusercontent.com/tagspaces/tagspaces/develop/resources/tagspacesp.cmd)
Once downloaded, place these files in the same directory where the TagSpaces executable is located.
### On macOS
Extract the content of the DMG files, to the place where you want to have the portable version, e.g. a USB stick. Open the command line for this folder and run:
```bash
./TagSpaces.app/Contents/MacOS/TagSpaces -p
```
This will start the app in portable mode and create the `tsprofile` folder in the current folder. All the setting for the portable version will be stored in this folder.
### Updating the Portable Version
To update a portable version of TagSpaces (e.g., on a USB stick), you simply need to replace the existing files and directories with the updated ones from the new installation package. Since the tag library and locations are stored in the `tsprofile` folder during portable mode, special care should be taken to preserve this folder during the update. Follow these steps to upgrade:
1. Rename your existing `tagspaces` folder (e.g., to `tagspaces_old`).
2. Extract the new TagSpaces zip file, which will create a fresh `tagspaces` folder.
3. Copy or move the `tsprofile` folder from the old `tagspaces_old` directory into the newly created `tagspaces` folder.
:::caution
**Important:** Do **not** delete the `tsprofile` folder as it contains crucial data for your portable TagSpaces setup.
:::
### Portable Mode with the AppImage Package (Linux Only)
The AppImage package offers another way to run TagSpaces in portable mode. AppImages are a distribution format that allows applications to run on various Linux distributions. This package format has its own [portable mode](https://docs.appimage.org/user-guide/portable-mode.html), which can be activated by creating an empty folder with the same name as your AppImage file, followed by `.config`.
For example, if your AppImage file is named `tagspaces-linux-x86_64-6.0.2.AppImage`, create an empty folder called `tagspaces-linux-x86_64-6.0.2.AppImage.config` in the same directory. This structure would look like:
```bash
tagspaces-linux-x86_64-6.0.2.AppImage
tagspaces-linux-x86_64-6.0.2.AppImage.config
```
From this point on, TagSpaces will store all configuration information in the `.config` folder instead of the default config folder in the user’s home directory. This setup allows you to run the application from, for example, a USB stick with the same configuration on different computers.
## TagSpaces Command Line Tool
This section has been moved [here](/dev/command-line-tools).
---
## User Documentation
Welcome to the official documentation for **TagSpaces**!
This guide will help you explore and understand the features, philosophy, and use cases of TagSpaces products.
## What is TagSpaces?
**TagSpaces** is an open-source, cross-platform file manager, organizer, and browser, designed with a no-backend and no-login philosophy. It empowers you to organize files, photos, and documents using tags on various platforms and devices. With a consistent and user-friendly interface, TagSpaces allows you to organize files according to your personal logic and preferences.
## Key Features
- Platform-independent and future-proof tagging for files and folders
- Add descriptions to files and folders in a platform-independent way
- Integrated free text and tag search (supports AND, OR, and NOT operators)
- Viewers for a variety of image, video, audio, and document file formats
- Editors for HTML, text, and markdown files
- Support for user interface themes (including dark mode)
- Thumbnail previews for numerous file types
## Philosophy - Offline first
- **No Backend, No Login:** TagSpaces follows a no-backend, no-login philosophy, meaning it works entirely offline without needing an internet connection.
- **Local File System as a Backend:** TagSpaces is a front-end application that uses your file system (or object storage) as the backend.
- **Database-Free:** Metadata is stored in your files and folders, preventing data loss in case of crashes, and eliminating vendor lock-in.
- **Sync-Friendly:** Use cloud services like Dropbox, NextCloud, or Google Drive to easily synchronize tagged files between devices.
- **Searchable:** Tags stored in filenames can be searched using your operating system's search functionality.
## Product Landscape
TagSpaces offers several products to cater to different user needs:
- **[TagSpaces Lite](https://www.tagspaces.org/products/lite/):** The community-developed edition of TagSpaces for Windows, macOS, and Linux.
- **[TagSpaces Pro](https://www.tagspaces.org/products/pro/):** An extended solution with advanced features for power users.
- **[TagSpaces Pro Web](https://www.tagspaces.org/products/proweb/):** A self-hosted package for managing files on web infrastructure with object storage support.
- **[TagSpaces Custom](https://www.tagspaces.org/products/custom/):** Tailored for enterprise use.
- **[Web Clipper Extension](https://www.tagspaces.org/products/webclipper/):** Available for Chrome, Firefox, and Edge, this extension allows you to save webpages, webpage fragments, and screenshots as local files.
- **[Android App (deprecated)](https://www.tagspaces.org/downloads/):** A mobile app offering most of the desktop version's features on Android devices.
## Common Use Cases
TagSpaces is suitable for various use cases:
- Organizing files and folders
- Desktop search
- Note-taking
- Photo management
- Bookmark management
- Simple file manager
- eBook organizer
## Videos
This short introductory video shows TagSpaces in action:
### YouTube Channel
We maintain a [YouTube channel](https://www.youtube.com/channel/UCzfSaeg-7mpt96UI97zwbfQ) where we publish videos related to TagSpaces.
## Technology Stack
The front-end of TagSpaces is built with:
- JavaScript / TypeScript / HTML / CSS
- React / Redux / [MUI](https://mui.com/material-ui/)
Native APIs for file access are based on:
- Desktop versions for Windows, macOS, and Linux, powered by [Electron](https://www.electronjs.org/)
- Mobile versions for Android, powered by [Cordova](https://cordova.apache.org/)
- Web versions for managing files in object storages, powered by [AWS SDK for JavaScript](https://aws.amazon.com/sdk-for-javascript/)
---
## Link to files, folders and locations
One long-awaited feature in TagSpaces is the ability to create links between files, folders, and locations. Now, you can navigate seamlessly from one file to another, or to a folder or location. The description field of any file or folder can contain links to other entities. If you're using markdown for notes, you can also place these kinds of links directly into your markdown file content.
The context menu for every file and folder in the default perspective includes the option **Copy Sharing Link**, which generates a sharing link and copies it to your clipboard. This link can be used to create internal links to this file inside TagSpaces.
### Location IDs
:::info
When sharing links between TagSpaces users, make sure that the locations in their TagSpaces installation have the **same IDs**; otherwise, the links will not work. These links also work in folders synced with services like Dropbox or Syncthing.
:::
You can change the location ID in the location's properties, as shown in the following screenshot. For S3 locations, ensure that the location connects to the same subfolder of the connected bucket.
### Links in the web versions of TagSpaces
Users of the web versions can directly copy the URL from their browser or use the copy button in the properties area.
:::info
Copying the URL from the browser has an advantage: the person receiving the link can open the same installation directly in their browser.
:::
### Opening TagSpaces links from the search
If you've received a TagSpaces link (e.g., a tslink) in an email or chat, you can copy and paste it into the search field. Running the search will open the location, file, or folder the tslink points to.
### Under the hood
TagSpaces links can point to locations, files, or folders. They follow these formats:
```bash title="Link to a location"
ts://?tslid=53ea7417-4f7c-9c25-dc44aa41f6c8
ts://?tslid=53ea7417-4f7c-9c25-dc44aa41f6c8
```
```bash title="Sharing link for a file"
ts://?tslid=53ea7417-4f7c-9c25-dc44aa41f6c8&tsepath=%2FMyHome%2Ftodos%5B202109%5D.md
```
```bash title="Sharing link for a folder"
ts://?tslid=53ea7417-4f7c-9c25-dc44aa41f6c8&tsdpath=%2FPersonal%20Knowledge
```
:::info
In version 5.1, the protocol prefix for links was changed from ts:? to ts://? for better compatibility. Links created in older versions with ts:? are still supported for backward compatibility.
:::
Technically the links consist of some parameter embedded in the URL.
- `ts://?` - Indicates that this is a TagSpaces link (tslink).
- `&tslid` - Represents the TagSpaces location ID.
- `&tsepath` - Encoded relative path to the entry.
- `&tsdpath` - Encoded relative path to the folder.
- `&tseid` - The unique id of a file or folder.
:::tip
Renaming or deleting a file or folder linked in a tslink will make the link unusable. However, TagSpaces will attempt to open the valid part of the link (e.g., the location). If the tslink contains a `tseid`, a search for this id will be offered by the application, so if a file or a folder with this id is still in the location it will be found.
:::
---
## Style Guide
## Markdown Syntax
To serve as an example page when styling markdown based Docusaurus sites.
## Headers
# H1 - Create the best documentation
## H2 - Create the best documentation
### H3 - Create the best documentation
#### H4 - Create the best documentation
##### H5 - Create the best documentation
###### H6 - Create the best documentation
The corresponding markdown:
```
# H1 - Create the best documentation
## H2 - Create the best documentation
### H3 - Create the best documentation
#### H4 - Create the best documentation
##### H5 - Create the best documentation
###### H6 - Create the best documentation
```
---
## Emphasis
Emphasis, aka italics, with _asterisks_ or _underscores_.
Strong emphasis, aka bold, with **asterisks** or **underscores**.
Combined emphasis with **asterisks and _underscores_**.
Strikethrough uses two tildes. ~~Scratch this.~~
The corresponding markdown:
```
Emphasis, aka italics, with _asterisks_ or _underscores_.
Strong emphasis, aka bold, with **asterisks** or **underscores**.
Combined emphasis with **asterisks and _underscores_**.
Strikethrough uses two tildes. ~~Scratch this.~~
```
---
## Lists
1. First ordered list item
1. Another item
- Unordered sub-list.
1. Actual numbers don't matter, just that it's a number
1. Ordered sub-list
1. And another item.
- Unordered list can use asterisks
* Or minuses
- Or pluses
The corresponding markdown:
```
1. First ordered list item
1. Another item
- Unordered sub-list.
1. Actual numbers don't matter, just that it's a number
1. Ordered sub-list
1. And another item.
- Unordered list can use asterisks
* Or minuses
- Or pluses
```
---
## Links
[I'm an inline-style link](https://www.google.com/)
[I'm an inline-style link with title](https://www.google.com/ "Google's Homepage")
[I'm a reference-style link][arbitrary case-insensitive reference text]
[You can use numbers for reference-style link definitions][1]
Or leave it empty and use the [link text itself].
URLs and URLs in angle brackets will automatically get turned into links.
Some text to show that the reference links can follow later.
[arbitrary case-insensitive reference text]: https://www.mozilla.org/
[1]: http://slashdot.org/
[link text itself]: http://www.reddit.com/
The corresponding markdown:
```
[I'm an inline-style link](https://www.google.com/)
[I'm an inline-style link with title](https://www.google.com/ "Google's Homepage")
[I'm a reference-style link][arbitrary case-insensitive reference text]
[You can use numbers for reference-style link definitions][1]
Or leave it empty and use the [link text itself].
URLs and URLs in angle brackets will automatically get turned into links. http://www.example.com/ or and sometimes example.com (but not on GitHub, for example).
Some text to show that the reference links can follow later.
[arbitrary case-insensitive reference text]: https://www.mozilla.org/
[1]: http://slashdot.org/
[link text itself]: http://www.reddit.com/
```
---
## Images
Here's our logo (hover to see the title text):
Inline-style: 
Reference-style: ![alt text][logo]
[logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 2"
Images from any folder can be used by providing path to file. Path should be relative to markdown file.
The corresponding markdown:
```
Inline-style: 
Reference-style: ![alt text][logo]
[logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 2"
```
---
## Code
```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```
```python
s = "Python syntax highlighting"
print(s)
```
```
No language indicated, so no syntax highlighting.
But let's throw in a tag.
```
```js {2}
function highlightMe() {
console.log("This line can be highlighted!");
}
```
---
## Tables
Colons can be used to align columns.
| Tables | Are | Cool |
| ------------- | :-----------: | -----: |
| col 3 is | right-aligned | \$1600 |
| col 2 is | centered | \$12 |
| zebra stripes | are neat | \$1 |
There must be at least 3 dashes separating each header cell. The outer pipes (|) are optional, and you don't need to make the raw Markdown line up prettily. You can also use inline Markdown.
| Markdown | Less | Pretty |
| -------- | --------- | ---------- |
| _Still_ | `renders` | **nicely** |
| 1 | 2 | 3 |
The corresponding markdown:
```
| Tables | Are | Cool |
| ------------- | :-----------: | -----: |
| col 3 is | right-aligned | \$1600 |
| col 2 is | centered | \$12 |
| zebra stripes | are neat | \$1 |
| Markdown | Less | Pretty |
| -------- | --------- | ---------- |
| _Still_ | `renders` | **nicely** |
| 1 | 2 | 3 |
```
---
## Blockquotes
> Blockquotes are very handy in email to emulate reply text. This line is part of the same quote.
Quote break.
> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can _put_ **Markdown** into a blockquote.
---
## Inline HTML
Definition list
Is something people use sometimes.
Markdown in HTML
Does *not* work **very** well. Use HTML tags.
---
## Line Breaks
Here's a line for us to start with.
This line is separated from the one above by two newlines, so it will be a _separate paragraph_.
This line is also a separate paragraph, but... This line is only separated by a single newline, so it's a separate line in the _same paragraph_.
---
## Admonitions
:::note
This is a note
:::
:::tip
This is a tip
:::
:::important
This is important
:::
:::caution
This is a caution
:::
:::warning
This is a warning
:::
---
## Powered by MDX
You can write JSX and use React components within your Markdown thanks to [MDX](https://mdxjs.com/).
export const Highlight = ({children, color}) => ( {children} );
Docusaurus green and Facebook blue are my favorite colors.
I can write **Markdown** alongside my _JSX_!
---
## FolderViz Perspective
This perspective is a collection of views that apply information visualization techniques to analyze and represent files, folders and tags. While this perspective started as a showcase of TagSpaces' capabilities for developing custom solutions, some of its features may also be beneficial for end users.
The perspective currently offers five views, accessible from the main toolbar located as usual on the top of the perspective. **Clicking** on a file or folder will display an overlay showing a thumbnail (if available) and additional details. Double-clicking on a folder will navigate to it, while **double-clicking** on a file will open it in the file preview area. **Click and drag** on the view will move the visualization. **Scrolling** with the mouse will zoom in and out.
Click on the **legend** elements on the top of the visualization will toggle the visibility of the corresponding entries in the graph.
In the **vertical menu** located in the top left part of the views you will find some useful commands, like redrawing the graph, changing its appearance or hiding the vertical menu in order to not have it on screenshots.
The colors of the files are the same use for the file extension and can be configured in the [settings](/ui/settings/#file-types). The color of the tags are coming from the [tag library](/ui/taglibrary).
## Folder Tree View
This shows an expanded, folder tree, similar to MindMap. While useful for visualizing folder hierarchies, it may struggle with performance in folders with many files.
## Circular Folder Tree View
Shows the same information like the folder tree view but in a circular tree.
## Links Graph View
This view uses the index created by the full-text search in a given location to show links between files and folder and their links to external website. The arrow connecting linked entries show the direction of the link. Only file and folder participating in a link will be displayed here.
:::info
- Full-text search should be enabled for the location in order to have a link extraction.
- The links are extracted from files in plain text, Markdown, HTML or PDF formats and from the description of any files or folder.
- The links between the files and folder should be in the in the tagspaces' [link format](/linking) in order to be displayed here.
:::
## Tags Graph View
The visualization show all the used tags with the tagged entries in a given location. Double-click on a tag will start a search for this tag and will show the files and folder tagged with it.
## Treemap View
The TreeMap View represents files and folders as tiles, where the size of each tile corresponds to the file size relative to others in the same folder hierarchy. This provides a visual understanding of file sizes in relation to the root and each other.
---
## Gallery Perspective
This perspective offers basic image gallery functionality, including previewing images from the current folder and a presentation mode with full-screen viewing.
:::tip
This perspective can only be activated in folders containing images and photos in file formats such as JPG, PNG, GIF, BMP, SVG, WEBP, etc.
:::
## Functionalities in the Toolbar
The toolbar of the gallery perspective offers the following functionalities:
- **(1) Navigate to parent folder** - Opens the parent folder of the current folder.
- **(2) Switch to masonry view** - Returns to the initial masonry view.
- **(3) Folder properties** - Opens the [properties](/ui/userinterface#folder-properties) of the current folder.
- **(4) Open previous/next image** - Navigates to the previous or next image file in the current folder.
- **(5) Start/stop presentation mode** - Toggles the slideshow presentation mode, displaying images from the current folder for 3 seconds each. (Future releases will allow configurable durations.)
- **(6) Full screen mode** - Opens the currently selected file in full screen mode.
- **(7) File properties** - Opens the properties of the current file in the regular properties area.
- **(8) Thumbnail bar modes** - Toggles through thumbnail bar positions: at the top, on the left, or hidden. These modes apply in full screen mode as well.
- **(9) Import EXIF/IPTC** - Opens the dialog to import EXIF/IPTC information from your files.
- **(10) Help** - Opens this page for further guidance.
:::tip
In full-screen mode, you can navigate through the files using the left and right arrow keys on your keyboard. On touch-screen devices, images can be changed by swiping left or right.
:::
## Importing EXIF/IPTC Data from JPGs
Many digital cameras embed additional metadata, such as geolocation, in the photos they capture. One common format for this metadata is [EXIF](https://en.wikipedia.org/wiki/Exif). Another format is [IPTC](https://en.wikipedia.org/wiki/IPTC_Information_Interchange_Model), which is often used for embedding keywords and descriptions in JPG files. The gallery perspective can read and convert the following data into TagSpaces' tags:
- **EXIF geolocation** - Converts latitude and longitude into geo-tags using [Plus Code](https://maps.google.com/pluscodes/) or MGRS format.
- **EXIF shooting date and time** - Converts the shooting date and time into a date-time tag.
- **IPTC keywords** - Imports IPTC keywords as regular tags.
---
## Grid Perspective
This perspective is optimized for general browsing through file and folder structures while supporting common file management operations such as tagging, renaming, deleting, copying, and moving files and folders.
The default view in TagSpaces presents content in a grid, making it the most common way of displaying folders.
### File Tile
Each tile in the grid represents the following information:
- **(1)**: Displays tags added to the file.
- **(2)**: Shows file description, if available.
- **(3)**: Displays the file title (filename without extension or tags).
- **(4)**: Shows the file extension, color-coded based on settings in the [File types tab](/ui/settings#file-types).
- **(5)**: Indicates the last modified date of the file.
- **(6)**: Shows the file size, hovering over it reveals the size in bytes.
- **(7)**: Indicates file selection (with a green border).
- **(8)**: Displays a file thumbnail, if available.
- **(9)**: Highlights a [geo-tag](/ui/taglibrary/#geo-tagging) with a special icon.
:::info
Adding descriptions and geo-tags to a file is a feature available in the Pro versions of the app.
:::
### Folder Tile
Similar to file tiles, folder tiles display the following:
- **(1)**: Shows tags added to the folder.
- **(2)**: Displays the folder description, if available.
- **(3)**: Shows the folder name and, if set, the [custom color](/ui/userinterface#folder-properties-area).
- **(4)**: Displays a folder icon (instead of a file extension).
- **(5)**: Displays a folder thumbnail, if available.
- **(6)**: Shows selection status for the folder.
:::info
Adding descriptions and thumbnails for folders is a feature available in the Pro versions of the app.
:::
### Selecting Files
Files can be selected by holding the `CTRL` / `CMD` key and clicking on them. To select a range, hold `SHIFT`, click on the first file (_file 1_), then click on the second file (_file 2_). This selects all files between _file 1_ and _file 2_.
To select or deselect all files, use the first button in the perspective's toolbar or press `CTRL+A` / `CMD+A`.
## Perspective Toolbar
The toolbar at the top of the perspective contains the following buttons and sub-menus:
- **(1) Open parent folder** - Navigates to the parent folder of the current folder, if within the current location. This action can also be achieved by pressing the **BACKSPACE** key.
- **(2) Toggle File Selection** - Selects or deselects all files and folders in the perspective.
- **(3) Open Folder Properties** - Opens the folder properties.
- **(4) Add/Remove Tags** - Manages tags on selected files, applicable to multiple files simultaneously. Learn more in the [Tagging -> Tagging using context menus](/tagging#tag-operations-on-many-entries) section.
- **(5) Copy/Move Entries** - Opens the **Move or Copy Entries** dialog to specify the target directory for moving or copying files.
- **(6) Delete Files** - Opens a dialog to confirm the deletion of selected files.
- **(7) Sort Files** - Opens a menu to sort files by the following options:
- **Title** - Sorts alphabetically by name.
- **Size** - Sorts by file size.
- **Date Modified** - Sorts by last modified date.
- **First Tag** - Sorts alphabetically by the first tag.
- **File Ext.** - Sorts alphabetically by file extension.
- **Random** - Sorts files randomly, useful when using TagSpaces as a music player for random audio track playback.
:::tip
Clicking a sorting option twice reverses the sort order. For random sorting, this regenerates a new random order.
:::
:::info
Sort order is preserved when navigating to a new folder.
:::
- **(8) Export as CSV** - Feature is described [below](#export-files-as-csv).
- **(9) Open Perspective Settings** - Opens the perspective settings dialog, described [below](#perspective-settings).
## File Context Menu
Right-clicking a file opens the context menu with options for file management.
- **Open File** - Splits the main area of TagSpaces, opening the file in the right pane. Learn more in the [Viewing Files](/viewing-files) section.
- **Open Parent Folder** - Useful in search results to open the parent folder of a selected file.
- **Open File Natively** - Opens the file in the default external application.
- **Show in File Manager** - Opens the file in your operating system’s default file manager.
- **Add/Remove Tags** - Opens a dialog to manage tags for the file.
- **Rename File** - Opens a file renaming dialog.
- **Duplicate File** - Creates a copy of the file, with tags for "copy" and timestamp (e.g., "20210831T1230").
- **Move/Copy File** - Opens the move/copy dialog.
- **Use as Thumbnail for the Current Folder** - Sets the file’s thumbnail as the folder thumbnail.
- **Delete File** - Opens a deletion confirmation dialog.
- **Copy Sharing Link** - Copies an internal sharing link for the file to your clipboard.
## Folder Context Menu
Right-clicking a folder opens its context menu for folder management.
- **Open Folder** - Navigates to the selected directory.
- **Open in New Window** - Opens the folder in a new TagSpaces window or tab (web version).
- **Rename Folder** - Opens the folder renaming dialog.
- **Move/Copy Folder** - Opens the dialog to move or copy the folder.
- **Delete Folder** - Opens a deletion confirmation dialog.
- **Show in File Manager** - Opens the directory in the default file manager.
- **Use as Thumbnail for Parent Folder** - Sets the folder’s thumbnail as the parent folder thumbnail.
- **Copy Sharing Link** - Copies a link for internal sharing or linking.
- **Add/Remove Tags** - Opens the dialog to manage folder tags.
- **Folder Properties** - Opens the folder properties in the preview area.
## Perspective Settings
Adjust the grid perspective settings in the dialog below.
Settings Options
- **Show Folders** - Toggles folder visibility.
- **Show Tags on Files and Folders** - Shows/hides tags as small colored circles.
- **Show Descriptions for Files and Folders** - Shows/hides descriptions.
- **Show Folder Details** - Shows/hides folder details.
- **Toggle Thumbnail Modes** - Switches between "cover" and "contain" modes for thumbnails. "Cover" may crop thumbnails, while "contain" shows the entire image with possible transparent bars.
- **Sort** - Choose default sorting for the perspective.
- **Compact Mode** - Condenses display mode with reduced space for file/folder representation.
- **Default Mode** - Standard display mode.
- **Large Mode** - Enlarges file/folder representation.
- **Single Click Opens File Internally** - Opens files in the application with a single click.
- **Single Click Opens File Externally** - Opens files in an external application with a single click.
- **Single Click Selects Only** - Selects the file without opening it.
:::info
Double-clicking always opens a file in the preview area or navigates to a folder.
:::
At the bottom of the dialog, you’ll find these options:
- **Help** - Opens this page from the online documentation.
- **Set as Default** - Saves the settings as the default for all folders with this perspective.
- **Set for This Folder** - Saves the current settings for the folder, so these options will be applied upon opening.
The dialog also indicates if the current folder has custom settings. You can reset them using the **Reset Custom Settings** button.
### Example Configurations
A common arrangement found in file browsing applications is the grid. The grid view offers a resizable grid with thumbnail previews of certain file formats, for quick and effective browsing. The files and folder are represented by user interface element called cards.
The following screenshot shows the grid view in its **compact mode**. The thumbnails are in the so called **cover** mode, covering the whole area defined for the thumbnail. In order to achieve this effect this mode will more likely cut some of the border areas of the thumbnail's image. The folder details is turned on in the screenshot.
The next screenshot shows the grid view in its **large mode**. The thumbnails here are in the **contain** mode, which displays the whole thumbnail in the thumbnail area of the card, eventually causing transparent bars to appear on the left and right side of the thumb image. The folder details is turned off in the screenshot.
## Drag to move within TagSpaces
An alternative way to move files into another folder is to drag it icon onto a folder on the **Folder navigation** area on the left panel. When the folder lights up with a greenish hue, just release the dragged item, and the file will be immediately moved into that folder.
:::tip
You can access sub folders of any folder displayed in the hierarchy, by clicking the folder icon next to its name.
:::
## Export files as CSV
With this feature you can export the list of file and folder from the current folder or from the current search results as CSV file. This will allow you to process the information annotations you have entered in TagSpaces such as tags and description in other tools. The export can be started by clicking on the button from the main toolbar of the default perspective, marked on the next screenshot.
The exported file contains the following columns:
- **name** - name of the entry
- **is file** - true if the entry is a file, false if it is folder
- **file extension** - only for files
- **tags** - a semicolon separated list of tags
- **size** - in bytes
- **last modified date** - ISO8601 compatible timestamp of the last modification
- **full path** - the full path to the current entry
- **description** - the entry description in markdown format
---
## Kanban Perspective
This perspective shows the first five subfolders of the current folder as columns of a Kanban board. Additional subfolders can be turned on later. The cards in the columns represent the files of the subfolders and can be used to organize tasks or other items. The cards can be moved between columns via drag and drop. Moving cards within a column will persist their order. Columns themselves can also be moved via drag and drop.
## Why is this useful?
Kanban boards have many potential uses. Here are some typical examples:
- **Personal Kanban**
- **Tracking software development**
- **Task management**
- **Recruiting process board**
- **Weekly plan** – Have each day of the week as a column and track activities or document progress like a diary.
## General functionalities
Below is a description of the buttons in the main toolbar of this perspective:
- **Navigate to parent folder** – Self-explanatory.
- **Folder properties** – Opens the folder properties in the right panel, allowing you to add tags, descriptions, and set the background color or custom wallpaper for the current folder.
- **Show the content of the current folder** – Useful for distributing files from the current folder into the columns (subfolders).
- **Toggle visibility of subfolders** – Displays the content of the current folder as an additional column on the far left. Useful for moving files from the current folder to other columns.
- **Import Kanban board** – Opens a dialog for importing a Trello board. Details are provided below.
- **Perspective settings** – Opens a dialog with settings specific to the Kanban perspective.
## Actions for Columns
Beyond moving columns via drag and drop, there are additional actions for each column. In the bottom right corner of every column, there's a plus icon that opens the dialog for [creating files](/creating-files).
The three-dot icon in the top-right corner of each column opens a menu with the following options:
- **Hide** – Hides the column. You can show it again using the toolbar button mentioned earlier.
- **Move Left** – Switches the column with the one to the left.
- **Move Right** – Switches the column with the one to the right.
- **Reload Folder** – Reloads the content of the folder.
- **Show in File Manager** – Opens the default file manager of your operating system with the preselected folder.
- **New File / Note** – Opens the dialog for creating new files.
- **Folder Properties** – Opens the folder properties, where you can change the background color, set a wallpaper image, or choose a thumbnail for the folder.
## Migration of Trello Boards
This perspective includes an importer for Trello boards exported as JSON files. To use a Trello board in TagSpaces, you must first export it as JSON. This can be done by navigating to the board's menu (top-right corner) and selecting "More," then "Print and export," and finally "Export as JSON." Save the file locally for easy access during import.
Once you have the JSON file on your computer, open TagSpaces, navigate to the folder where you want to import the Trello board, and switch to the Kanban perspective. Click the "Import Kanban" button and select "Choose Trello JSON file" from the dialog.
### Mapping the Trello Board to Files and Folders
| Trello | TagSpaces | Comment |
| ------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Card | Markdown file | For each card, a text file in markdown format is created, including: description, checklist, link to attachments, link to the original card in Trello, and the timestamp of the import. |
| Column | Folder | The order of the tasks in the columns is preserved as they are imported into the Kanban folders. |
| Labels | Tags | The labels of the exported board are imported as [location-based tags](/ui/taglibrary/#location-tags). The importer tries to preserve the colors of the labels. All labels are transformed to lowercase by the importer. |
## Perspective Settings
The settings for this perspective can be accessed from the last button in the perspective's toolbar.
The following options can be adjusted in the settings dialog:
- **Show folders** – Displays subfolders as columns, if available.
- **Show tags** – Toggles between showing the full name of the tags or just a symbol indicating the presence of tags.
- **Show content of the current folder** – Toggles the display of the current folder column on or off (same as the button in the toolbar).
- **Show folder details** – Displays the name and a preview of the folder description above the columns of the board.
- **Toggle thumbnail modes** – Switches between two modes for displaying thumbnails on the cards: cover and contain.
- **Size of the files/tasks in the column** – Adjusts the width of the tiles between compact, default, and large.
- **Definition of the single click** – Customizes the behavior of single-click actions.
---
## List Perspective
This perspective is optimized for general browsing through files and folders and performing standard file and folder operations. It features three representation modes: compact, default, and large.
The following information can be found on every row representing a file in this view:
- **File extension** - A color-coded icon, representing the file type. Scroll down to [Color-coded file extensions](#color-coded-file-extensions) to learn more about this feature.
- **Folder icon** - On rows representing folders, instead of the file extension, a folder icon is displayed.
- **Title** - The file's title, which is the filename without the extension or any tag information.
- **Description** - If the file/folder has a description, it will be displayed here.
- **Tags** - All the tags that are applied to the file will appear here, with the correct background and font color. To learn more about tag colors, refer to the [Tag Library](/ui/taglibrary) section.
- **Size** - The file size, displayed in a human-readable format.
- **Date modified** - The time the file was last modified.
:::info
The functionalities of the list perspective are very similar to the **[grid perspective](/perspectives/grid)**. Please follow the previous link for more details.
:::
## Customizations
## Compact mode
## Perspective Settings
Perspective settings are described in the [grid perspective](/perspectives/grid#settings-options).
---
## Mapique Perspective
This perspective is useful for visualizing geo-tagged files and folders.
Here are some ideas for which this perspective can be used:
- Saving favorite places privately
- Planning trips and places to visit
- Showing pictures taken on trips
- Placing any file or document on a map
- Adding private annotations to a map
## Supported Maps
The default map shown when opening this perspective is provided by [OpenStreetMap](https://www.openstreetmap.org/).
An optional topological map is provided by [OpenTopoMap](https://opentopomap.org/) and looks as shown in the following screenshot.
## User Interface
From the main toolbar of this perspective, the user can access the following functionalities:
- **Parent folder** - Will open the parent folder in this perspective if possible.
- **Details** - Will open the properties of the current folder.
- **Extract geo tags** - Start the extraction of geo coordinates from JPG files with embedded EXIF/IPTC located in the current directory.
- **Geo tag current folder** - Takes the location of the current map center and adds it as a geo tag in [Plus Code format](https://en.wikipedia.org/wiki/Open_Location_Code) to the current folder.
- **Change the map type** - Clicking this button will iterate through the currently supported map types, which for now include: OpenStreetMap (default) and topographical.
- **Show folders** - Will show the a list of all sub-folders of the current folder, so you can navigate to them. This is useful if some of the folders are not geo-tagged or currently not visible on the map.
- **Help** - Clicking this button will open this page.
Clicking on the popup of a file on the map will open the file in the previewing area of TagSpaces, where you can add or change the file description, rename the file, or choose another thumbnail. The following screenshot shows a comparison.
### Smart Pin Icon
With the help of a small pictogram, you can directly recognize if the pin is for a file or a folder. The small tile in the center represents the first tag of the file or folder with its color. This allows you to visually recognize tagged files and folders. In the following screenshot, for example, each pin represents a geo-tagged file representing one person. The first tag is the year of birth, with the years organized in decades using different colors. The colored pins on the map help illustrate the age distribution of these individuals, which could allow for building clusters.
## Navigating Tagged Folders
Since TagSpaces supports tagging of folders, you can geo-tag folders, making them displayable in the Mapique perspective. In the following screenshot, you can see that folders have a dedicated icon, differentiating them from files. Clicking on a folder icon will open a small popup, which when clicked, will navigate to the selected folder.
Not all folders have geo tags, so the Mapique perspective only shows files and folders with such tags. This can be problematic when trying to navigate through a folder tree. To address this, a new button has been added to the main toolbar of the Mapique perspective. This button toggles an overlay displaying all subfolders of the current folder. Once turned on, the user can seamlessly navigate deep within a folder tree, even if there are no geo tags. The following video demonstrates how this works.
## Encoding Geo Tags
By default TagSpaces uses [Plus Codes](https://en.wikipedia.org/wiki/Open_Location_Code) for encoding geo locations. Plus codes encode coordinates such as **48°08'27.8"N 11°34'53.6"E** into a short string like **8FWH4HRJ+CJ**, making the format ideal for use as tags. As alternative the geo tags can be encoded in [MGRS](https://en.wikipedia.org/wiki/Military_Grid_Reference_System) format.
---
## Quick Access
# Quick Access Area
The quick access section can be accessed from the left drawer and looks like this:
This section contains the following areas:
- **[Stored Search Queries](/search#stored-search-queries)** - contains prepared search queries for a later use, more on this in the [search section](/search/#stored-search-queries)
- **[Bookmarks](/bookmarks)** - contains a list of bookmarked files and folders, more on this in the [bookmark section](/bookmarks)
- **Recently opened files** - contains a list of recently opened files
- **Recently edited files** - contains a list of recently edited files
- **Recently opened folders** - contains a list of folders opened in the details section
Since version 6.6 every bookmarks or recently visited entries have its own context menu containing the following operations:
- **Open entry** - will open the entry in the current application window
- **Open in new window** - will open the entry in a new application window or browser tab if on the web version.
- **Copy the link to the clipboard** - will copy the link of the bookmarked file to clipboard, so it can be shared will somebody else working on the same files
- **Remove** - will remove the file or folder from the list
## Configuring the recently opened entries
The amount of the collected files can be adjusted in the advanced tab of the settings. Here you can also clear the history or deactivate the collection of the recent entries by choosing the _disabled_ menu item in dropdowns.
---
## Search Overview
In order to offer desktop search functionalities, TagSpaces provides a variety of search-related features, which are described in this section.
With the search functionality, you are able to find files and folders by their name, tags, and other properties. The search algorithm considers different weights for the following properties of the [indexed](#indexing) entries:
- The name of the file or the folder
- The tags assigned to the file or the folder
- The description added to the file or the folder
- The name of the parent directory of a given file is also considered by the search algorithm. For example, if you are searching for photos from your vacation in the USA and the folder where these files are located contains the word USA (e.g., '20160301 vacation usa'), the search will list all the files located directly in this folder.
- The content of TXT, MD, and HTML files if the [full-text search](#full-text-search) is activated for the current location.
## Open the search
The user can start a search by switching to the search area by pressing the `Ctrl+F` / `Cmd+F` key combination. It can also be opened by clicking on the search text field.
Once activated, you can start entering the tags or other search [terms](#search-query). If you choose to enter tags with the `+` symbol, you will see suggestions **(1)** and you can choose from them with the arrow `UP` and `DOWN` keys. The search can be started by hitting the `ENTER` key or by clicking on the search button **(4)**. You can close the search mode with the `ESC` key or by clicking on the X-button **(3)**.
The **advanced search options**, visible in the next screenshot, can be accessed after clicking on the button with the sliders **(2)** from the previous screenshot.
## Search query
The search query consists of two parts. The first one is just a simple free text that is searched in the index. The second component is a list of tags. Here, you can define a more precise query by including and excluding tags. You can use the following shortcuts to add, remove, or exclude certain tags:
- `+` - Will add the tag to the **Must contain all of the tags** field - logical AND
- `|` - Will add the tag to the **At least one tag** field - logical OR
- `-` - Will add the tag to the **None of these tags** field - logical exclusion
The tags specified here will be visible in the search options described in the previous [paragraph](#search-for-tagged-entries).
Example search queries:
- **"+usa +beach -sunset jpg"** - Will find all files and folders having `jpg` in the name and having the `usa` and `beach` tags but not the `sunset` tag.
- **"|beach |sunset"** - Will find all files and folders having the tags `beach` or `sunset`.
### Search query composition
As usual, the search can be opened by the `CTRL+SHIFT+F` (`⌘+SHIFT+F` on Mac) key binding. The opened dropdown has two sections. The first is called **Actions**, which will be described below, and the second is **Search query composition**. This allows you to easily compose complex search queries, combining or excluding tags, choosing file size limits, types, and details.
The following commands are currently supported:
- **AND tag** - Typing `+` will show the list of all tags in the dropdown so you can select tags that should be present in every file or folder in the search results.
- **NOT tag** - Typing `|` will show the list of all tags in the dropdown so you can select tags that may be present in files or folders in the search results, e.g., files tagged with "tag1" or "tag2."
- **OR tag** - Typing `-` will show the list of all tags in the dropdown so you can select tags that should be excluded from the search results.
- **File type** - Typing `t:` will present a list of supported file type groups, helping to narrow down the search results to documents, images, etc.
- **File size** - Typing `s:` will present a list of predefined file sizes.
- **Last modified** - Typing `lm:` will present a list of predefined points back in time.
- **Search scope** - Typing `sc:` will allow you to choose from the following search scopes: current folder, current location, global search in all locations.
- **Search accuracy** - Typing `a:` will allow you to toggle the search accuracy between fuzzy, semi-strict, or strict.
### App actions
In the search menu, you can also start some common actions just by using your keyboard. The following commands are currently supported:
- **Locations** - Typing `l:` will list the current locations, allowing you to easily find and open one by typing the first few letters.
- **Filter** - Typing `f:` will filter the current content of the folder without starting a new search.
- **History** - Typing `h:` will list the last opened or edited files so you can filter and open one of them.
- **Bookmarks** - Typing `b:` will allow you to filter and open your bookmarked files or folders.
- **Saved search query** - Typing `q:` will allow you to filter and start your saved search queries.
- **Search history** - Typing `s:` will allow you to find and execute search queries you have used in the past.
### Search scope
The search algorithm can be required to deliver results for the following search scopes:
- **Location** - will deliver results from the current location. This is the default scope.
- **Folder** - will deliver results for the current folder, including all sub-folders.
- **Global** - will search in all configured locations. You can find more in the [Global Search](#global-search) section.
### Search accuracy
The following three types of searches are supported:
- **Fuzzy** - will deliver broader search results, tolerating typos in the search query.
- **Strict** - will deliver exact search results.
- **Semi-strict** - similar to strict but case insensitive.
### Search for tagged entries
To support detailed search for tags, the user interface for entering them is split into three input fields:
- **Must contain all of the tags** - all tags listed here must be attached to the files or folders for them to appear in the search results (**logical AND**).
- **At least one tag** - any file or folder containing one of the tags listed here will be included (**logical OR**).
- **None of these tags** - entries with any of the tags listed here will be excluded from the search results (**logical exclusion**).
## Search filters
### Filter by file type
In the file type dropdown, you can specify which types of files to search. The file types are grouped into the following sections:
- **Pictures and Photos**: e.g., JPG, PNG, GIF
- **Documents**: e.g., PDF, ODF, DOCX, EXL
- **Notes**: e.g., MD, TXT, HTML
- **Audio files**: e.g., OGG, MP3, WAV
- **Video files**: e.g., WEBM, OGV, MP4
- **Archives**: e.g., ZIP, RAR, TGZ, 7Z
- **Bookmarks**: e.g., URL, LNK
- **eBook**: e.g., EPUB, MOBI, AZW, PRC
- **Emails**: e.g., EML, MSG
In addition, there are special filters:
- **Folders** - limits the search to only folders.
- **Files** - limits the search to only files.
- **Untagged files and folders** - displays only files and folders that are not tagged.
### Filter by file size
In this dropdown, you can filter files by their size. The following options are supported:
- **Empty** - filters files with zero size.
- **Tiny** - filters files smaller than 10KB.
- **Very small** - filters files smaller than 100KB.
- **Small** - filters files smaller than 1MB.
- **Medium** - filters files smaller than 50MB.
- **Large** - filters files smaller than 1GB.
- **Huge** - filters files larger than 1GB.
### Filter by creation and last modified date
Here you can specify the time period in which the files you're searching for should have been modified. This filters supports the following options:
- **Today** - shows files and folders modified today.
- **Yesterday** - shows results modified yesterday.
- **Past 7 days** - shows results modified in the last 7 days.
- **Past 30 days** - shows results modified in the last 30 days.
- **Past 6 months** - shows files and folders modified in the last 6 months.
- **Past year** - shows files and folders modified in the last 12 months.
- **More than one year** - shows files and folders older than one year.
### Filter by time period
This filter limits search results to files and folders that have date-time tags pointing to a certain time period.
### Filter by GPS coordinates
This filter is planned.
## Indexing
TagSpaces has an integrated file and folder search functionality based on an **index**, which is created when you hit the search button. By default, the index is valid for 10 minutes. This time can be adjusted individually in the properties of each [location](/ui/locations/#local-locations). The idea is that some locations may contain files that do not change often, so a longer validity period, like 1 month, can be applied.
If your location contains a large number of files (>50,000), it is recommended to split it into two or more locations or to [disable the indexing](/ui/locations#local-locations).
If you decide to disable automatic indexing, you should manually update the index regularly to maintain working and accurate search functionality. The index can be updated in the following ways:
- In the menu of each location in the location manager, there is an item called "Refresh Location Index."
- All indexes can be updated at once from the search menu with the option "Update all location indexes."
- Create the index manually with the [command line tools](/dev/command-line-tools).
## Limit the search results
By default, TagSpaces limits the number of search results to 1,000 files and folders. This limitation also applies to the maximum number of files that can be displayed in a single folder. In the [general](/ui/settings#general) tab of the settings, there is a field where you can increase or decrease this limit. See the next screenshot.
## Full text search
TagSpaces PRO supports full text search for text (.TXT), markdown (.MD), HTML and searchable PDF files. You can activate this feature for each location individually in the "Edit Location" dialog, as seen in the following screenshot. Once activated (see the screenshot below), during the indexing of a given location, the application will extract the text content of the supported files and create a keyword list that will be considered in the search algorithm.
:::caution
On locations with many large text files, activating this feature may slow down the application's performance, so be careful where you activate it.
:::
These file formats are currently supported:
- **HTML** - files in HTML format, used for rich text notes.
- **MD** - markdown files.
- **TXT** - plain text files.
- **PDF** - searchable PDF documents (already OCR-ed).
:::caution
This feature is still in beta and could lead to performance issues if you have many or large text files.
:::
## Global search
TagSpaces Pro offers searching across all locations, called "Global search." It works on both local and remote S3-based locations. You can activate this feature by clicking the _Global_ button in the search area, as shown in the following screenshot.
Once in _Global search_ mode, you will see an additional option called "Force re-indexing all locations." Activating this checkbox will force TagSpaces to create a new index for each location before searching in it. This option delivers the most accurate search results but may take more time, especially when re-indexing remote locations or locations with many files.
All other search settings work the same as in single location searches. The [search result limit](#limiting-the-search-results) applies here; once the limit is reached, TagSpaces will stop the search and not continue searching the remaining locations.
:::info
If you are in the context of a given [workspace](/workspaces), the global search will deliver only result from the location assigned to the current workspace.
:::
## Search history
This feature can be activated in the app's advanced settings, where you can choose how large the search history should be. Once activated, the app will save the last searches performed, including the search query and the location where they were executed.
The search history can also be **disabled** by choosing _disabled_ from the dropdown or **deleted** by clicking the trash bin icon.
## Stored search queries
This feature allows you to store commonly used search queries for later use. The following video demonstrates how to use this feature.
:::tip
Stored searches are location-independent, meaning they can be executed on any location.
:::
### Create stored searches
### Edit stored searches
### Export and import
This functionality allows you to share commonly used search queries with others who are working with you on the same file base.
In the three-dot menu of the stored search area, you will find menu entries for exporting and importing search queries. The file format for the export is JSON, which can be opened and edited with any modern text editor. If needed, you can fine-tune the search queries in the editor and distribute them to other TagSpaces installations for yourself or colleagues.
Due to the unique IDs associated with search queries, TagSpaces can recognize if the query has already been imported, allowing you to skip the re-import or import the newer version. An example export can be found in the [documentation](/dev/metafileformats#format-of-the-exported-search-queries).
---
## Setup Self-hosted TagSpaces based on WebDAV
:::caution
Deprecated functionality: The here described functionality is not supported anymore.
:::
## Motivation
Almost since the very first releases of TagSpaces back in the 2013, many users did requested a server based version of TagSpaces. They wanted to use the convenient tagging workflow of TagSpaces on their self hosted Nextcloud/ownCloud or in general WebDAV instances. So starting from today this is possible, TagSpaces can now run on servers and once installed you can access your files from anywhere.
## Download and Installation
The current version can of the WebDAV version can be downloaded from [here](https://github.com/tagspaces/tagspaces/releases).
> **Note** Please handle the current status of the implementation is a technology preview, which in our opinion is still not suitable for production use on Internet.
In order to use the hosted version you need a working WebDAV server. The current release was tested with success on [ownCloud](http://owncloud.org) which is based itself on the [sabre/dav](http://sabre.io) WebDAV server. On Ubuntu the installation steps are as following:
- Install Apache webserver (_nginx_ webserver with its webdav extension is reported also to work)
- Install [Nextcloud](https://nextcloud.com/install/)/[ownCloud](https://owncloud.org/install) or any other WebDAV server
- Unzip the hosted version of TagSpaces somewhere in the www root folder of Apache. Currently the TagSpaces should be on the same host/ip and using the same port as the WebDAV server. This is so because of the XSS prevention build in the modern internet browsers.
- Assuming _ownCloud_ is installed in `/var/www/owncloud` and TagSpaces in `/var/www/tagspaces` you have to type something like this in your terminal:
```
cd /var/www
sudo chmod -R 755 tagspaces
sudo chown -R your_www_group:your_www_user tagspaces
```
- Open your browser and enter: `127.0.0.1/tagspaces`. The TagSpaces UI should be loaded.
- Create a new location with the following path: `/owncloud/remote.php/webdav`
- Give a name to your location and save.
- A dialog for credentials entering will appear. Enter here your ownCloud username and password.
- That's all, you can now browse your files in TagSpaces.
:::tip
If the dialog prompting for the user credentials does not appear and you have running Nextcloud/ownCloud in some other browser tab, you have to logout there and reload the tab running TagSpaces.
:::
It is interesting to mention that you can open also your ownCloud contacts by creating a location with a path like `/owncloud/remote.php/carddav/addressbooks/ilian/contacts`. This does not make currently much sense, because you only see a list with VCF files, but who knows perhaps somebody will write a contacts perspective and VCF viewer for TagSpaces some day.
## Demo
You can experience a live demo of the TagSpaces webdav version on [demo.tagspaces.org](http://demo.tagspaces.org). The username and password are both `demo`.
## Sharing links to files from the webdav version
tbd
## Starting the WebDAV edition locally for testing
There is a script called `webdavserver.js` located in the data/web , which can be started with:
node data/web/webdavserver.js
or
npm run webdav
This command will start a local node.js based WebDAV server on `http://127.0.0.1:8000`. Open your browser and enter the following URL:
http://127.0.0.1:8000/index.html
You will be prompted for user credentials, which are username: `demo` and password: `demo` and now you should be able to work with the WebDAV version of TagSpaces.
---
## Share files and folders
You can share files in two ways, and here is how it can be done.
## Internal sharing for files and folders
The first method, introduced back in version 3.8, is called "Sharing." It allows you to share links to files and folders with other TagSpaces users and installations. These links will work for object storage locations or local locations synced with tools such as Dropbox, Google Drive, or Syncthing. A key requirement is that these locations must have the [same location ID](/linking#location-ids).
Once copied to the clipboard with the **COPY** button, the link can be shared, for example, via email or messenger. The recipient must open TagSpaces, paste the link into the search box, and press enter.
Alternatively the **Open Link** button from the next screenshot can be used for this purpose.
:::info
These kinds of links can also be used for internal links within TagSpaces. More details can be found in the dedicated [linking section](/linking).
:::
## Download links for files on object storage
The second type of sharing links, called "Links for downloading," are available only for files (not folders) located on object storages such as AWS S3 or MinIO buckets. The relevant section in the file properties is shown in the next screenshot.
Clicking the **Generate Link** button opens the following dialog:
Here you have the following options:
- Adjust the **validity duration** of the link. Supported durations include: 15 minutes, 1 hour, 1 day, 3 days, and 1 week.
- The **Copy** button copies the link to the clipboard for use in other applications.
- A **QR-code** of the link is automatically generated. Changing the duration will regenerate the QR-code.
The generated link can be shared via chat or email. When opened in a browser, the download will be initiated. If the link expires, the user will see this message:
### Downloading directly in locations
It is possible to download files via links directly into a TagSpaces location, bypassing the browser. Click on the **Create new** button and from the menu choose **New From URL**
This will open the following dialog, where you can paste the URL and start the download with the **OK** button.
### Downloading to your phone
You can also download files to your phone or tablet. Point your device’s camera at the QR-code, and it will automatically recognize the link, allowing you to open it in your mobile browser. This is an easy way to transfer files from object storage to mobile devices.
## Sharing multiple files at once
To share files from a folder, a selection of files, or search results, you can use the "Share many files" feature. This functionality is available in the [Grid](/perspectives/grid), [List](/perspectives/list), and [Kanban](/perspectives/kanban) perspectives. To open the sharing dialog, click the sharing icon in the toolbar or select the share option from the context menu in these perspectives.
The dialog generates sharing links that are valid for 3 days by default. You can adjust the validity duration to 15 minutes, 60 minutes, 1 day, 3 days, or 7 days. After expiration, the links will no longer work. TagSpaces does not offer permanent sharing links.
The center of the dialog, surrounded by a dashed line, shows a preview of the generated HTML snippet. If the shared files have thumbnails, they will be displayed; otherwise, the filenames will be shown. The expiration date of the links is displayed at the top of this area.
At the bottom of the dialog, you have the following options:
- **Copy to clipboard** - Copies the generated code with the links to the clipboard, so you can paste it into an email or chat application.
- **Save as HTML** - Saves the generated code locally as an HTML file, which can be attached to an email.
- **Save & Share** - Saves the generated HTML file to the S3 bucket and opens the sharing dialog, allowing direct sharing of the file.
- **Close** - Closes the dialog.
- **Help** - Opens this help page in the online documentation.
:::caution
If the links have not expired, anyone with the code snippet can access and download the shared files. So be cautious with whom and how you share this code.
:::
### Using the HTML snippet in email clients
Here is how the HTML snippet appears when pasted into some common email clients.
#### Thunderbird
:::info
In Gmail, make sure to uncheck the "Plain text mode" option, as marked in the screenshot below, to ensure the links are recognized.
:::
#### Gmail
#### Outlook
### Using the HTML snippet in chat apps
This is how the HTML snippet looks when pasted into common chat applications.
#### Signal
#### Whatsapp
---
## Supported file formats
The following table lists the supported files types for viewing and editing of files in TagSpaces.
## 3D formats
File format
Preview
Thumbnail
Edit
Extension
STL
yes
yes, after opening the file
no
3D Viewer
OBJ
yes
yes, after opening the file
no
3D Viewer
GLB
yes
yes, after opening the file
no
3D Viewer
GLTF
yes
yes, after opening the file
no
3D Viewer
## Image formats
File format
Preview
Thumbnail
Edit
Extension
PNG
yes
yes
no
Image Viewer
JPG
yes
yes
no
Image Viewer
SVG
yes
yes
no
Image Viewer
GIF
yes
yes
no
Image Viewer
AVIF
yes
yes
no
Image Viewer
WEBP
yes
yes
no
Image Viewer
BMP
yes
yes
no
Image Viewer
TGA
yes
yes
no
Image Viewer
ICO
yes
yes
no
Image Viewer
TIF
yes
yes
no
Image Viewer
DNG
yes
yes
no
Image Viewer
CR2
yes
yes
no
Image Viewer
NEF
yes
yes
no
Image Viewer
PSD
yes
yes, after opening the file
no
Image Viewer
## Documents formats
File format
Preview
Thumbnail
Edit
Extension
PDF
yes
yes
no
PDF Viewer
MD/MARKDOWN
yes
no
yes
MD Editor,{" "}
MD Viewer or{" "}
Text Editor
RTF
yes
no
no
eBook Viewer
HTML
yes
yes
no
HTML Viewer
RTF
yes
no
no
eBook Viewer
DOCX
yes
yes
no
Document Viewer
XLSX
yes
yes
no
Spreadsheet Viewer
ODS
yes
yes
no
Spreadsheet Viewer
CSV
yes
no
no
Spreadsheet Viewer
## Audio / Video formats
File format
Preview
Thumbnail
Edit
Extension
WEBM
yes
yes
no
Media Player
MP4
yes
yes
no
Media Player
ACC
yes
no
no
Media Player
FLAC
yes
no
no
Media Player
OGG
yes
no
no
Media Player
OGV
yes
no
no
Media Player
OGA
yes
no
no
Media Player
OGV
yes
no
no
Media Player
OGX
yes
no
no
Media Player
SPX
yes*
no
no
Media Player
OPUS
yes*
no
no
Media Player
MKV
yes
no
no
Media Player
3GP
yes
yes
no
Media Player
3G2
yes
no
no
Media Player
## eBook formats
File format
Preview
Thumbnail
Edit
Extension
EPUB
yes
yes
no
eBook Viewer
## Bookmark formats
File format
Preview
Thumbnail
Edit
Extension
URL
yes
yes
no
URL Viewer
DESKTOP
yes
no
no
URL Viewer
WEBSITE
yes
no
no
URL Viewer
## Email formats
File format
Preview
Thumbnail
Edit
Extension
EML
yes
no
no
MHTML Viewer
MSG
yes
no
no
MSG Viewer
## Archive formats
File format
Preview
Thumbnail
Edit
Extension
ZIP
yes
yes
no
Archive Viewer
## Font formats
File format
Preview
Thumbnail
Edit
Extension
TTF
yes
yes, after opening the file
no
Font Viewer
WOFF
yes
yes, after opening the file
no
Font Viewer
OTF
yes
yes, after opening the file
no
Font Viewer
## Text and source code formats
File format
Preview
Thumbnail
Edit
Extension
TXT
yes
no
yes
Text Editor
XML
yes
no
yes
Text Editor
JS
yes
no
yes
Text Editor
JSON
yes
no
yes
JSON Editor
CSS
yes
no
yes
Text Editor
H
yes
no
yes
Text Editor
CLJ
yes
no
yes
Text Editor
COFFEE
yes
no
yes
Text Editor
CPP
yes
no
yes
Text Editor
CS
yes
no
yes
Text Editor
GROOVY
yes
no
yes
Text Editor
HAXE
yes
no
yes
Text Editor
JAVA
yes
no
yes
Text Editor
JSM
yes
no
yes
Text Editor
LESS
yes
no
yes
Text Editor
LUA
yes
no
yes
Text Editor
ML
yes
no
yes
Text Editor
MLI
yes
no
yes
Text Editor
PL
yes
no
yes
Text Editor
PHP
yes
no
yes
Text Editor
PY
yes
no
yes
Text Editor
RB
yes
no
yes
Text Editor
SH
yes
no
yes
Text Editor
SQL
yes
no
yes
Text Editor
---
## Organizing Files and Folders with Tags
## Why Tagging?
Tagging is a versatile approach to organizing files and folders. Unlike predefined categories, tagging lets users label items with words that reflect their personal understanding. It enhances searching and helps categorize files like songs, books, documents, and more in a user-defined way. Tags are personal, providing the freedom to define and group files as you see fit.
Tagging is more than just organization; it's a way of expressing your thoughts and emotions. Instead of conforming to someone else's categories, you define what matters to you. Think of it as a form of personal expression or even a type of "freedom of speech."
One of the core functionalities in TagSpaces is the ability to add tags to files and folders. Unlike other products, **TagSpaces does not rely on a central database for storing tags**. Instead, it offers two alternative methods, which are described in the following sections.
## File Tagging
TagSpaces supports two methods for tagging files: embedding tags in file names and using sidecar files. Both methods work on any file type and across all supported operating systems.
### Storing Tags in File Names
This method embeds tags directly into the file name. For example, adding the tags `vacation` and `alps` to an image named `IMG-2653.jpg` will rename it to `IMG-2653[vacation alps].jpg`.
**Advantages:**
- **Durable and Portable:** Tags persist across platforms like Dropbox and Google Drive.
- **Compatibility:** Tags are visible and searchable using any file browsing software.
**Drawbacks:**
- **File Path Length Limitations:** Some operating systems (like Windows) restrict the file path length to around 256 characters, which can limit how many tags you can add.
Once embedded in the name of file, the tag stick there and can be removed only by file renaming. **This makes the tagging "durable" and portable**. The tags embedded in the name of a file "survives" synchronization across cloud platforms such as Dropbox and Google Drive and can be read by TagSpaces or any other file searching software on Windows, macOS or Linux.
:::tip
File name tagging may run into limitations due to file path length restrictions on certain operating systems like Windows.
:::
### Storing Tags in Sidecar Files
As an alternative to embedding tags in file names, TagSpaces allows storing tags in sidecar files within a hidden `.ts` folder. This can be activated in the settings for all locations or per location in the properties of every location.
When tagging a file, TagSpaces will create a corresponding sidecar file with the same name as the source file but with a `.json` extension. For example:
```
~ location (with your files)
├── subfolder1
│ ├── .ts
│ │ ├── file1.jpg.json <-- contains the tags and the description for file1.jpg
│ │ └── file2.pdf.json
│ ├── file1.jpg
│ └── file2.pdf
├── .ts
│ ├── file3.png.json
│ └── file4.docx.json
├── file3.png
└── file4.docx
```
**Advantages:**
- **File Integrity:** Tags are stored separately, preserving the original file name.
- **Unlimited Tags:** There is theoretically no limit to the number of tags you can add.
**Drawbacks:**
- **Manual Maintenance:** If files are moved or renamed outside of TagSpaces, you must also move or rename the corresponding sidecar files manually.
- **Synchronization Issues:** Hidden `.ts` folders may not sync with cloud services unless explicitly enabled.
:::tip
To sync `.ts` folders with cloud services like Dropbox or Google Drive, enable the synchronization of hidden folders and files.
:::
## Folder Tagging
Tags added to folders are always saved in sidecar files. The file is located in the `.ts` subfolder and is called `tsm.json`.
```
~ location (with your files)
├── subfolder1
│ ├── .ts
│ │ ├── tsm.json <-- contains tags and description for subfolder1
│ │ └── file2.pdf.json
│ └── file2.pdf
├── .ts
│ └── file4.docx.json
└── file4.docx
```
:::tip
To sync `.ts` folders with cloud services like Dropbox or Google Drive, enable the synchronization of hidden folders and files.
:::
## Tag Operations on Multiple Entries
To add or remove tags from multiple files or folders, first, select them by holding the CTRL/CMD key and clicking on the entries with the left mouse button. You can also use checkboxes in the list view.
Once selected, right-click on the files and choose `Add / Remove Tags` from the context menu, or click the `Tags` button in the toolbar.
This will open a popup dialog for managing tags.
The options in the dialog are:
- **Clean all tags:** Removes all tags from the selected files.
- **Remove tags:** Removes the specified tags. You have to manually enter the tags which you want to be remove from the selected files.
- **Add tags:** Adds the specified tags to the selected files.
### Adding Multiple Tags at Once
You can add multiple tags at once by separating them with commas in the tagging dialog.
## Tagging in File and Folder Properties Area
Tags can also be added in the properties area by selecting them from a dropdown or dragging them into the tagging area. To remove a tag, click the open the three-dots menu next to the tag and choose `Remove tag`.
## Tagging with Drag and Drop
Tagging can also be performed using drag-and-drop. Here are the supported operations:
### Dragging a tag from the tag library to a file or folder
This action is supported in the [grid](/perspectives/grid), [list](/perspectives/list) and [kanban](/perspectives/kanban) perspective.
### Dragging a tag to the tagging section of the details area
This actions is supported in the details of files and folders and can be initiated from the tag library or from a file or folder in the [grid](/perspectives/grid) and [list](/perspectives/list) perspectives
### Dragging a tag from one file or folder to another
This action is supported in the [grid](/perspectives/grid) and [list](/perspectives/list) perspectives.
---
## Thumbnail Generation
When a user opens a folder, the application automatically scans its contents and attempts to generate mini-previews, or thumbnails, for the files in the folder.
## Thumbnails on Local Folders
When you navigate to a folder, TagSpaces will try to generated automatically thumbnails for the supported file types in this folder. The following file types are supported, a full list can be found [here](/supported-file-formats).
- **Images:** PNG, JPG, BMP, GIF, SVG, WEBP, TIFF
- **Videos:** WEBM, OGV, MP4, M4V
- **Notes:** HTML (utilizing embedded screenshots, if created with the TagSpaces [Web Clipper](/web-clipper/))
- **Text Files:** TXT, MD, source code files (using the first lines found in the file)
- **Bookmarks:** URL (using the embedded screenshot, if created with the TagSpaces [Web Clipper](/web-clipper/))
- **Ebooks:** EPUB (using the integrated ebook cover image)
- **Archives:** ZIP (using the first image found in the archive)
- **Office Documents:** PDF, ODT, ODP, ODS, DOCX, XLSX, PPTX (using embedded preview images, if available)
The generated thumbnails are stored in the `.ts` folder located within each folder you browse. This caching mechanism significantly improves the speed of browsing folders containing many files. Thumbnail generation can be enabled or disabled in the application settings.
## Thumbnails on S3 Locations
When you upload files to an S3 location, TagSpaces will attempt to generate thumbnails during the upload process.
---
## How to use Cloudflare R2 buckets as locations
[Cloudflare](https://www.cloudflare.com/) is a globally distributed network platform known for its CDN, DNS, and security services.
Its **R2 Object Storage** is an affordable, S3-compatible storage solution designed for developers and small teams who want to store data in the cloud **without egress fees** — a major advantage compared to traditional cloud providers.
R2 integrates easily with many S3-compatible tools, including **TagSpaces**, allowing you to use it as a remote file location for tagging, browsing, and organizing your content.
**Advantages**
- No egress bandwidth fees
- S3-compatible API
- Hosted on Cloudflare’s globally distributed infrastructure
- Integrated with Cloudflare Workers and CDN
After registration, you’ll see the **R2 Object Storage** dashboard, which lists your existing buckets.
From this screen, you can create new buckets and manage the **API tokens** needed to connect with TagSpaces.
---
## Creating a bucket
In the R2 dashboard, click **Create Bucket** to open the setup screen.
Here, you can choose:
- **Bucket name** – this will be required later in TagSpaces
- **Storage location** – choose your preferred data region and jurisdiction
- **Storage class** – standard or low-frequency, depending on your usage
Once created, go to the **bucket settings** page.
Here you’ll find the **S3 API endpoint URL**, which will be required when setting up the connection in TagSpaces.
## Creating access tokens
Access tokens are required to connect your Cloudflare R2 bucket to TagSpaces.
They can be created directly from the R2 overview screen.
Go to **Manage API Tokens** and from the next screen choose **Create User API token**:
Here you specify the following settings:
- **Permissions** – choose Read, Write, or Admin
- **Bucket access** – specify which buckets the token can access
Once created, you’ll receive your **Access Key ID** and **Secret Access Key** — store them securely, as they are only shown once.
---
## Connecting the bucket to TagSpaces
Now it’s time to connect your **Cloudflare R2 bucket** to **TagSpaces**.
1. Open **TagSpaces**.
2. Click the **New** button and select **New Location**.
3. In the dialog, set the **Location Type** to **Object Storage**.
4. Fill in the following fields:
- **Location name** – any name you prefer
- **Bucket name** – your R2 bucket name (e.g. `ts-dev`)
- **Access key** and **Secret key** – your R2 API credentials
- **Endpoint URL** – your R2 S3 API endpoint, e.g.
`https://.r2.cloudflarestorage.com`
Once all fields are filled, click **OK** to create the location.
You can now browse, tag, and organize files stored in your Cloudflare R2 bucket directly from TagSpaces.
## Conclusion
By connecting **Cloudflare R2** to **TagSpaces**, you can manage your files in a fast, global, and cost-efficient way — ideal for users who want the scalability of the cloud combined with TagSpaces’ tagging and organization features.
R2’s S3 compatibility means you retain flexibility: you can move your data between services or self-hosted alternatives without vendor lock-in, keeping your files accessible and under your control.
TagSpaces + Cloudflare R2 = simple, flexible, cloud storage on your terms ☁️🔐
---
## How to use Contabo to store your files
[Contabo](https://contabo.com/de/object-storage/) offers affordable cloud infrastructure and storage solutions hosted in Germany and other EU locations. Currently (October 2025) they are offering 250 GB for roughly 3 € per month, which sound very reasonable. For users in the European Union or those concerned about **GDPR compliance**, Contabo provides a strong alternative to US-based cloud providers by keeping your data under strict EU privacy and data protection laws. Another advantage is the unlimited and free traffic for downloading and uploading files from/to the object storage.
In this tutorial, we’ll walk through how to set up **Contabo Object Storage** as a location in **TagSpaces**, allowing you to manage, tag, and browse your files directly from Contabo’s S3-compatible storage.
---
## Creating a bucket
1. **Create a Contabo account** at [contabo.com](https://contabo.com) and log in.
2. Navigate to **Storage → Object Storage**.
3. Click **Create bucket** to make a new storage bucket.
Once created, you’ll see your bucket appear in the **bucket list**:
You can optionally adjust the **bucket properties** such as name purchase space, auto-scaling, and other options:
---
## Getting the access tokens
To connect your bucket with external tools like TagSpaces, you’ll need API access with **S3 credentials**.
1. Go to your **Account → Security & Access** section.
2. Scroll down to find the **S3 Object Storage Credentials** area.
3. There, you’ll find your **Access Key** and **Secret Key** — these will be required later.
---
## Connecting the bucket to TagSpaces
Now it’s time to connect your Contabo storage to **TagSpaces**.
1. Open **TagSpaces**.
2. Click the **New** button and select **New Location**.
3. In the dialog, set the **Location Type** to **Object Storage**.
4. Fill in the required fields:
- **Location name** – any name you prefer
- **Bucket name** – the name of your Contabo bucket
- **Access key** and **Secret key** – from the previous step
- **Endpoint URL** – the endpoint from your bucket list
:::important
Remove the **bucket name** from the URL when entering it into TagSpaces, e.g.: https://eu2.contabostorage.com/.
:::
Once everything is set, click **OK** to create the location.
You can now browse, tag, and organize your Contabo files directly in TagSpaces!
---
## Creating additional users with restricted rights
If you want to give others limited access to your buckets, Contabo allows creating **additional user accounts**.
1. Go to **Account → User Management**.
2. Click **Create User**.
3. Enter the email address of the user who should have access.
4. Choose the appropriate permission level:
- **Full access**
- **Read only**
- **Read and write**
:::warning
These permissions apply **globally to all buckets** — per-bucket permissions are not yet supported.
:::
Click **Create** to finalize the new user.
The new user can log into the Contabo admin console, navigate to
**Account → Security & Access → S3 Object Storage Credentials**, and obtain their own access and secret keys.
---
## Conclusion
By connecting **Contabo Object Storage** with **TagSpaces**, you can build your own privacy-respecting, self-managed cloud system — a personal alternative to Dropbox or Evernote.
You maintain **full control** over your data, stored safely under **EU GDPR standards**.
While Contabo’s management tools are still developing (for example, limited per-bucket permissions), it remains an excellent choice for users who value **data sovereignty**, **cost efficiency**, and **GDPR compliance**.
---
:::info Congrats
You now have your own cloud-based TagSpaces location hosted in the EU!
:::
---
## E2E encryption with Cryptomator
Evernote's recent [change in its pricing plans](https://blog.evernote.com/blog/2016/06/28/changes-to-evernotes-pricing-plans/), restricting non-paying users to only two machines, have been an eye-opener to many. Even though the cloud-crazed hype is trying to convince us otherwise, with all the marketing tools at its disposal, keeping your private data in the cloud, and especially via vendor-locked solutions such as Evernote, had never been a good idea. With such vendor-locked, proprietary services, you do not own your own data, and have no control over its storage, meaning access to your own notes might be severely limited at any time, as it happened just recently.
[TagSpaces](https://www.tagspaces.org/) had long been offering an alternative, self-hosted note-taking solution. Its capable RichText (HTML) and MarkDown editors and previewers can easily replace proprietary software, the plain, flat-file storage paradigm allows total control, and unrestricted access. With the help of third party cloud storage providers, such as Dropbox or Google Drive, you can also easily keep your notes in sync.
Keeping your own files in your own cloud account is undoubtedly a better solution, but it still does not alleviate the problem of storing plain files on other people's computers (which is what servers, and the whole "cloud" really are.) To be reasonably safe, the best bet is to encrypt your data, before sending it off over the Internet.
## Encryption made easy
Encryption might sound daunting to the everyday user, and rightly so. It is a broad topic, there are many solutions, and implementations, often targeting the advanced user, or even the expert. If you just want to secure your notes, it might seem like a little too much work of work. And of course we all prefer an instant solution. This is where [Cryptomator](https://cryptomator.org/) comes into the picture.
Cryptomator is a free and open source, transparent, client-side encryption solution, which makes encrypting your cloud hosted files effortless. The cross-platform software is available for Windows, Mac, Linux, and as an executable Java `.jar`. The platform is absolutely service agnostic: Your encrypted files can be used with any cloud storage provider, as the encryption/decryption happens on your local machine, with as password provided by yourself. Cryptomator integrates into your OS's file system, making encryption as easy as a drag and drop operation in your file manager. How much easier could it be?
## Your encrypted Evernote alternative
From a note-taking perspective, the solution to replacing Evernote with its access-limit, vendor lock, proprietary file format, and "cloud only" approach (meaning "no Internet, no work", unless you buy premium, of course), is really simple with TagSpaces, and any cloud service you prefer. Add Cryptomator to the mix, and your notes are also secured.
### Setting up your encryption solution
First you will need to install **Cryptomator**, which is as easy as downloading the latest version for your platform from the Cryptomator [download site](https://cryptomator.org/downloads/), and running the installer. Next, you will need to connect a new _vault_, which in Cryptomator's terminology, means a folder that you connect to the software to create a virtual drive.
To connect a new vault:
- Open Cryptomator
- Click on the "+" icon on the lover left corner, and
- Select "Create new vault"
- In the file chooser, navigate to the local folder that is synced with your preferred cloud service
- And type a name for your vault.
Once you're done, your new vault should show up on the side pane of Cryptomator's main screen. The vault is now there but not functional, until you set up a password. this password will be used to generate the encryption keys, ensuring that you can easily encrypt/decrypt any file in the vault on ,multiple computers.
- Enter, and confirm a new password
- And press "Create Vault"
Now your new vault is ready to use. To unlock it, you need to enter your password. In the "More options menu underneath, you can change the drive name to whatever you like, and opt to save your password, so that you will not need to enter it on the local machine, each time you want to unlock it. This might be good for single user computers, but you should remember it's always a security risk to store your passwords.
As you enter your password, your vault should be unlocked and automatically mounted on your system. Your File Browser application will most likely fire up, showing your vault mounted as a new `dav` network drive. You can just begin to copy or move files and folders onto this drive, and they will be instantly encrypted by Cryptomator, without you noticing anything. To you all the files and folders will appear as if they were stored in their plain for mat on your file system.
You can also lock the vault any time from within Cryptomator by pressing "Lock"
This will unmount the drive and make the vault's contents unacceptable to anyone locally. When you unlock the vault, you will have full access again.
If open the folder where your vault is stored, you will only find encrypted data, inaccessible from outside Cryptomator's virtual device.
### Adding it to TagSpaces
To complete your setup, [download](https://www.tagspaces.org/downloads/) and install TagSpaces for your platform, if you have not already done so.
You can now easily access your vaulted files from within TagSpaces:
- Make sure Cryptomator is running and the vault containing your files is unlocked.
- Mount the drive, if you have to (although this should happen automatically)
- And connect it as a new location in TagSpaces.
> Important note: You should not be adding the folder in which the Cryptomator vault is located, but rather the virtual dav network drive, which Cryptomator creates. If you need more information about how to mount a drive, you should consult your operating systems's documentation, although Cryptomator should handle this step for you automatically.
Now you can access all your notes inside your Cryptomator vault from within TagSpaces, wile storing them encrypted for both on- and off-line use. If you now synchronize the folder with your cloud service of choice, you can rest assured that your files are safe, private and always accessible, without having to worry about the next policy change from Evernote, or any other proprietary cloud based note-taking service.
---
## Syncing files between TagSpaces installations
One of the most common questions I receive about TagSpaces, is about the missing files synchronization feature. The concerns of the users are that they spend an hour tagging their files on the laptop, but now they want to get the same results also on their tablet or desktop computer and vice versa. Our opinion here is that TagSpaces does not need sync functionality, because all the tags are saved in the names of the files or in the so called sidecar files, which makes this meta-information extremely portable between devices. You have to just to sync files and this problem is already perfectly solved by some many online services. This is one of the main differences between TagSpaces and other applications offering tagging on files. Most of those applications are using some kind of database to store the tags, which makes the transfer of this information challenging. Besides that, your tagging information in this case is locked by the vendor and you cannot migrate to another application or service without significant effort. Saving the tags in the file names make the information stick to your files, and you can find files based on the tags even with simple search functionality supplied with your operating system.
For the synchronization of the tagged files with TagSpaces, you can use any "cloud" service like [Dropbox](https://dropbox.com) or projects like [Nextcloud](https://nextcloud.com), which provides sync clients. And since there are TagSpaces clients for Windows, macOS and Linux), your tagged files can be synced and used almost everywhere.
Here is a short list of services which can be used for syncing tagged files and folders:
- Dropbox
- Google Drive
- Microsoft OneDrive
or other P2P projects like:
- [Syncthink](https://syncthing.net/) - a good tutorial explaining details about the TagSpaces/Synching setup can be found on [Medium](https://attilaorosz.medium.com/syncronise-your-offline-notes-across-all-devices-without-the-cloud-1e82fa53d1f1)
- Bittorentsync/Resilio
E2E Encryption can be achieved with [Cryptomator](https://cryptomator.org/). You can details about how to setup in this [tutorial](/tutorials/e2ee-with-tagspaces-and-cryptomator).
The following image shows a utilization of Dropbox in connection to TagSpaces. But this setup will most probably work with other service like Google Drive, MS OneDrive and other.
---
## Customizing Folders
# Turning folders into file based apps
WIP
## Ways to customize folders
- Choosing a default perspective
- Choosing folder thumbnail
- Choosing folder background color or gradient
- Choosing folder background image - visible in the grid, list and kanban perspective
- Adding folder description
- Customizations in the grid and list perspective
- Customizations in the kanban perspective
- Customizations in the mapique perspective
## What you can achieve
### Turning folder into photo gallery
### Turning folder into a kanban board
### Turning folder structure into wiki
---
## Exposing local folders as object storage with S3Proxy
## Introduction
The web version of TagSpaces can be used currently only with object storage as a backend. Such is offered by a countless cloud provider, starting with AWS from Amazon, Wasabi or R2 from Cloudflare. This is great if your files are located in the Cloud, but what if you want to connect your files from your NAS or other local shares, you will need local object storage server. And here comes [S3Proxy](https://github.com/gaul/s3proxy) in place. It is a web server, which can be used to expose local folders as S3 compatible buckets.
## Running S3Proxy as Docker container
Running the S3proxy with Docker is the way we recommend, especially if you already use Docker to run the [TagSpaces Web](/tutorials/tagspaces-web-docker) application.
```docker showLineNumbers
sudo docker run -d \
--restart=always \
-p 9000:80 \
--name s3proxy-local-fs \
-e S3PROXY_AUTHORIZATION=aws-v2-or-v4 \
-e S3PROXY_ENDPOINT="http://0.0.0.0:80" \
-e S3PROXY_IDENTITY="username" \
-e S3PROXY_CREDENTIAL="password" \
-e S3PROXY_IGNORE_UNKNOWN_HEADERS=true \
-e JCLOUDS_PROVIDER="filesystem" \
-e JCLOUDS_FILESYSTEM_BASEDIR="/data" \
-e S3PROXY_CORS_ALLOW_ALL="true" \
-v /Users/yourusername/buckets:/data \
andrewgaul/s3proxy \
```
Here is a short explanation of the docker command parameters. The parameter on line **(2)** is optional and makes Docker starting TagSpaces automatically after restart. Line **(3)** maps the internal port `80`, specified on line **(6)**, to port `9000` of the host computer, so TagSpaces Web can be accessed on `localhost:9000` or `127.0.0.1:9000`. On line **(4)** the name of the docker container is specified. Line **(13)** maps the host folder `/Users/yourusername/buckets` to the internal `/data` folder, which is the root folder of the S3Proxy server specified on line **(11)**.
:::info
Every sub folder in the `/Users/yourusername/buckets` folder is served as a separate bucket by the S3Proxy service, so the name of the sub folder should be used later as bucket name in TagSpaces.
:::
Line **(5)** is specifying the s3 authorization version, for TagSpaces Web and Desktop app you will need `aws-v2-or-v4`. On line **(7)** you should specify the username and on line **(8)** the password. Please change them according to your needs.
The local filesystem is specified as file backend on line **(10)**. Line **(12)** disables the CORS restrictions, so you can access the S3 service from any host running TagSpaces. This is not always recommended and can be restricted with other parameters from the S3Proxy [Dockerfile](https://github.com/gaul/s3proxy/blob/master/Dockerfile).
Line **(14)** specifies the name of the Docker image for the S3Proxy project, as published on [Docker Hub](https://hub.docker.com/r/andrewgaul/s3proxy/).
## Running S3Proxy as standalone program
You can start S3Proxy directly on your computer. On Linux or macOS you will need the program which can be downloaded from GitHub. You should make the `s3proxy` executable file with following command:
```
chmod +x s3proxy
```
And run it with the appropriate configuration file:
```
./s3proxy --properties s3proxy.conf
```
The content of the s3proxy.conf could be the following:
```conf showLineNumbers title="s3proxy.conf"
s3proxy.endpoint=http://127.0.0.1:9000
s3proxy.authorization=aws-v2-or-v4
s3proxy.identity=username
s3proxy.credential=password
s3proxy.ignore-unknown-headers=true
s3proxy.cors-allow-all=true
jclouds.provider=filesystem
jclouds.filesystem.basedir=/Users/yourusername/buckets
```
More details for installation and running the application on Windows can be found on the official [webpage](https://github.com/gaul/s3proxy) of the project.
## Connecting to TagSpaces
Now it’s time to connect your s3proxy bucket to **TagSpaces**.
1. Open **TagSpaces**.
2. Click the **New** button and select **New Location**.
3. In the dialog, set the **Location Type** to **Object Storage**.
4. Fill in the required fields:
- **Location name** – any name you prefer
- **Access key** and **Secret key** – as created earlier
- **Bucket name** – the name of any sub folder of the bucket folder, which was specified in the previous steps
- **Endpoint URL** – the URL with port of the s3proxy server, it could begin with `http` or `https`, depending on the utilization of SSL certificate
Once everything is set, click **OK** to create the location.
## Serving S3Proxy with SSL certificate
:::info
This is an important and recommended configuration, which is currently not covered by this tutorial. More details can be found here: https://github.com/gaul/s3proxy/wiki/SSL-support
:::
## Other use cases with S3Proxy
With S3Proxy you are able to connect some other cloud storage providers which does not support S3 directly. Some examples are:
- Azure Blob
- Backblaze B2
- Google Cloud Storage
- Rackspace Cloud Files
The corresponding configuration files can be found here: https://github.com/gaul/s3proxy/wiki/Storage-backend-examples
We haven't tried out all of them with TagSpaces, so any feedback will be valuable for us.
---
## How to use Garage buckets as locations
[Garage](https://garagehq.deuxfleurs.fr/) is an open-source distributed object storage system compatible with the **S3 API**.
It allows you to **self-host your own S3-compatible storage**, either on a personal server, a NAS, or even across multiple devices.
This makes Garage a perfect solution for **privacy-focused users** or teams who want to keep their data local while still benefiting from a modern, S3-compatible setup.
In this tutorial, we’ll show how to connect a Garage bucket as a **TagSpaces location**, enabling you to browse and manage files directly from your own Garage instance.
You can find Garage’s full setup guide here: 👉 [Garage Quick Start Documentation](https://garagehq.deuxfleurs.fr/documentation/quick-start/)
Below is a condensed version of the essential setup steps.
## Creating the config file
First, create a Garage configuration file `garage.toml` on macOS or Linux.
```toml
cat > garage.toml <
You can now browse and tag files stored in your Garage bucket directly from TagSpaces.
## Conclusion
By integrating Garage with TagSpaces, you can create your own fully self-hosted, S3-compatible file system — perfect for privacy-conscious users, home servers, or offline NAS setups.
This setup allows you to enjoy the flexibility of TagSpaces’ metadata and tagging features while keeping your data under your control — no external cloud providers needed.
Garage + TagSpaces = your personal, private cloud. ☁️🔐
---
## How to start
# Getting Started with TagSpaces
Welcome to **TagSpaces**, your privacy-friendly file manager and organizer.
This guide will help you get started quickly after downloading and installing the app.
---
## Launching for the First Time
When you start TagSpaces, after you accept the software license, you’ll be greeted by the **Welcome Screen**.
From here, you can:
- Create or connect a **location** (a folder you want to manage with TagSpaces)
- Explore the **intro tour** to understand the interface
- Open existing folders on your computer or cloud storage
:::tip
TagSpaces never uploads your data anywhere by default. All your files stay where they are — on your local drive. If your location is on object storage, then your files stay in this storage, unless your download them.
:::
---
## Understanding “Locations”
A **location** is simply a folder from your computer, an external drive, or an S3-compatible cloud bucket.
TagSpaces connect automatically some of your standard folders like the **Downloads**, **Documents**, **Music** and **Desktop**. The **Locations** are visible on the left area of the application window.
The standard locations are fully optional you can remove them or create new locations pointing to folders which contain files you want to manage in TagSpaces.
**To create a new location:**
1. Click the **“New button”** on the top left part of the main screen, and the choose **New Location** from the menu.
2. Click the folder icon to to choose a folder from your file system, which will be the root of your location.
3. Choosing the folder from your file system
4. Give the location a recognizable name.
TagSpaces takes automatically the name of the chosen folder as name for the location. You can change this name to something else in this dialog.
5. Now you can browse, tag, and organize all files inside that location directly within TagSpaces.
:::info Connecting cloud locations
TagSpaces can connect to folders located on object storage. The object storage can be hosted on a [NAS](/tutorials/folders-as-objectstorage-with-s3proxy) or in the Cloud like on [AWS S3](/tutorials/s3-bucket-locations), [Contabo](/tutorials/contabo-storage) [Wasabi](/tutorials/wasabi-locations) or [Cloudflare R2](/tutorials/cloudflare-r2-storage).
:::
---
## Tagging Your Files and Folders
Tags are at the heart of TagSpaces. They help you organize and find files faster.
The following video how you can apply tags to files and folder:
- By adding tags from the tag library using drag and drop
- By dragging tags from one file and dropping them onto another
- By using the tagging dialog to add and remove tags
You can group tags by category in [tag groups](/ui/taglibrary#tag-groups) — for example:
🧾 _Document Type_, 🎨 _Project_, 🌍 _Location_, or 📅 _Year_.
> ⚙️ **Tagging method:** Choose between storing tags in filenames or in sidecar files (`.json`).
> Adjust this in **Settings → Tagging Method**.
---
## Creating Notes and New Files
TagSpaces includes built-in editors for:
- **Markdown** (recommended for note-taking)
- **Plain text**
- **HTML** (for formatted documents)
- **Audio** (for dictation of audio notes)
**To create a note:**
1. Click the **“+ New”** button.
2. Select the type of file you want to create
3. Change the desired template (optional step)
4. Start typing
Your note is saved as a regular file in the current folder.
---
## Exploring Perspectives
**Perspectives** define how your files are displayed:
| Perspective | Description |
| ------------------------------------------------------ | ----------------------------------------------- |
| 🗂️ [Grid](/perspectives/grid) | Visual tile layout |
| 📋 [List](/perspectives/list) | Table-like view with sorting |
| 🖼️ [Gallery](/perspectives/gallery) | Ideal for image collections |
| 🗺️ [Mapique](/perspectives/mapique) | Display geo-tagged files on a map |
| 📊 [FolderViz](/perspectives/folderviz) | Visualize folder structures and tag connections |
| ✅ [Kanban](/perspectives/kanben) | Manage tasks as cards in a board |
Switch perspectives using the **Perspective Switcher** in the toolbar.
---
## Syncing Files Across Devices
TagSpaces works with any file synchronization service:
- Dropbox
- Google Drive
- Nextcloud
- Syncthing
- S3-compatible storage
Connect the same folder as a location on multiple devices to keep tags and notes synced.
---
## Customization and Themes
Personalize your workspace:
- Light and dark modes
- Adjustable language and default perspectives
- Custom folder background colors
- Tag color customization
---
## Next Steps
Now that you’ve created your first location:
- Add and tag files
- Write your first Markdown note
- Try switching perspectives
- Install the **[TagSpaces Web Clipper](https://www.tagspaces.org/products/webclipper/)** to save content from the web
> 🚀 **Pro Tip:** Upgrade to TagSpaces Pro for advanced perspectives, geo-tagging, and automation with local AI integrations.
---
## 💡 Additional Resources
- [Tutorials](/tags/tutorial/)
- [Community Forum](https://tagspaces.discourse.group/)
- [FAQ](https://www.tagspaces.org/faq/)
---
## Use custom map tile services in TagSpaces Pro
:::info
This article is work in progress
:::
TagSpaces uses the free OpenStreetMap service as a default digital map. It works fine for the most of the cases, but since the service is free, they can not guaranty that it we always accessible and that it can serve all the request coming to it. Depending on this how much you relay on the digital maps in TagSpaces, it might make sense to configure an alternative map tile server solution. They are many such services available online and we found [Maptiler](https://www.maptiler.com/) to be one which is very reliable, easy to configure and offering many map themes. Of course everything comes with its price, luckily they offer a free plan so you can try it with no costs. Another option you have is to setup your own map tiles server. I will discuss this option briefly at the end of the second half of this tutorial.
## Using map tiles from Maptiler
In order to start with Maptiler you will need to [create an account](https://www.maptiler.com/cloud/plans/) for this service.
https://cloud.maptiler.com/geocoding/
## Setting up your own map tile server
DockerImage
https://github.com/Overv/openstreetmap-tile-server
https://hub.docker.com/r/overv/openstreetmap-tile-server
http://download.geofabrik.de/
## Adding map tile servers in TagSpaces
## Other resources
- [Self Hosting a Google Maps Alternative with OpenStreetMap](https://wcedmisten.fyi/post/self-hosting-osm/) - a deep dive into the topics of self hosting OpenStreetMap
---
## Overview
# Tutorials and Guides
- [How to start](/tutorials/how-to-start/)
- [Collaboratively using tags and tag groups](/tutorials/sharing-tags/)
- [How I manage my ever growing collection of photos?](https://www.tagspaces.org/blog/photo-management-process/)
- [Using TagSpaces with other users or on many devices](/tutorials/using-tagspaces-collaboratively/)
## Advanced topics
- [Synchronize Your Offline Notes Across All Devices Without the Cloud](https://attilaorosz.medium.com/syncronise-your-offline-notes-across-all-devices-without-the-cloud-1e82fa53d1f1)
- [End to end encryption with Cryptomator](/tutorials/e2ee-with-tagspaces-and-cryptomator/)
- [Use custom map tile services in TagSpaces Pro](/tutorials/map-tiler-tutorial/)
- [Exporting and organizing photos from Flickr](https://www.tagspaces.org/blog/organize-flickr-export/)
## Hosting files in an object storage
- [How to use AWS S3 buckets as locations](/tutorials/s3-bucket-locations/)
- [How to use Contabo buckets as locations](/tutorials/contabo-storage/)
- [How to use Wasabi buckets as locations](/tutorials/wasabi-locations/)
- [How to use Cloudflare R2 buckets as locations](/tutorials/cloudflare-r2-storage/)
- [Exposing local folders as object storage with S3Proxy](/tutorials/folders-as-objectstorage-with-s3proxy)
- [How to use MinIO buckets hosted on NAS Server](/tutorials/setup-minio-bucket-nas/)
- [How to use Garage buckets as locations](/tutorials/garage-storage/)
## Web version of Tagspaces
- [Using TagSpaces Web with Docker](/tutorials/tagspaces-web-docker/)
- [Setup TagSpaces Web on a Web Server](/tutorials/setup-tagspaces-web/)
---
## Prepare custom packages
## Introduction
get zip or tag.gz package
unpack the tagspaces package
install asar
```
npm install -g asar
```
go to resources folder
create app subfolder
and extract the content of the asar file to the app folder
```
asar extract-file app.asar app
```
delete the app.asar files
edit the app.html in the main folder
```HTML
TagSpaces Desktop