External Configuration

External Configuration

This document will describe how to deploy TagSpaces Pro and Custom with predefined configuration such as custom logo and color, tag library or locations.

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 (for web) and extconfig.json (for desktop version), placed in the folder where the application is hosted.

:::tip Each JSON example represents a complete extconfig.json file and can be copied directly. You can combine the content of many JSON files in order to achieve the desired configuration. See the examples at the end of this document for more details. :::

Configuring a custom logo

For exchanging the application logo the ExtLogoURL parameter should be used. A valid values can be an URL:

window.ExtLogoURL = "https://www.tagspaces.org/content/text-logo.svg";
// window.ExtLogoURL = "custom-logo.png"; // an example with relative path to the logo

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtLogoURL": "custom-logo.png"
}

</TabItem> </Tabs>

:::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.

window.ExtShowTSLogo = false;

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtShowTSLogo": false
}

</TabItem> </Tabs>

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.

window.ExtShowTSVersion = false;

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtShowTSVersion": false
}

</TabItem> </Tabs>

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.

window.ExtIsFirstRun = true;

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtIsFirstRun": true
}

</TabItem> </Tabs>

The default value is true.

Disable the checking for new version on startup

window.ExtCheckForUpdatesOnStartup = false;

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtCheckForUpdatesOnStartup": false
}

</TabItem> </Tabs>

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.

window.ExtDisplayMode = "mobile";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtDisplayMode": "mobile"
}

</TabItem> </Tabs>

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.

window.ExtUseSidecarsForFileTagging = false;

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtUseSidecarsForFileTagging": false
}

</TabItem> </Tabs>

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.

window.ExtUseOnlyTagsFromTagLibrary = false;

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtUseOnlyTagsFromTagLibrary": false
}

</TabItem> </Tabs>

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.

window.ExtFilenameTagPlacedAtEnd = true;

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtFilenameTagPlacedAtEnd": true
}

</TabItem> </Tabs>

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:

window.ExtPrivacyURL = "https://tagspacesweb.yourdomain.com/privacy/";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtPrivacyURL": "https://tagspacesweb.yourdomain.com/privacy/"
}

</TabItem> </Tabs>

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:

window.ExtPrivacyURL = "https://tagspacesweb.yourdomain.com/imprint/";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtPrivacyURL": "https://tagspacesweb.yourdomain.com/imprint/"
}

</TabItem> </Tabs>

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:

<Tabs groupId=“config”> <TabItem value=“js” label=“extconfig.js”> ```js title="Example of object storage location" 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 as hosted in an object storage 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 }, ];

  &lt;/TabItem>
  &lt;TabItem value=“json” label=“extconfig.json”>
```json title="Example of object storage location"
{
  "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",
      "endpointURL": "https://nas34r:3000/minio",
      "isNotEditable": true,
      "isDefault": true,
      "isReadOnly": true,
      "disableIndexing": false,
      "disableThumbnailGeneration": false,
      "fullTextIndex": false,
      "watchForChanges": false,
      "maxIndexAge": 600000,
      "persistTagsInSidecarFile": true,
      "ignorePatternPaths": ["**/node_modules/**"]
    }
  ]
}

</TabItem> </Tabs>

The following snipped is an example for connecting a local folder as location:

<Tabs groupId=“config”> <TabItem value=“js” label=“extconfig.js”> ```js title="Example of local location" window.ExtLocations = [ { 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 }, ];

  &lt;/TabItem>
  &lt;TabItem value=“json” label=“extconfig.json”>
```json title="Example of local location"
{
  "ExtLocations": [
    {
      "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
    }
  ]
}

</TabItem> </Tabs>

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.

window.ExtSaveLocationsInBrowser = true;

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtSaveLocationsInBrowser": true
}

</TabItem> </Tabs>

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

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
  },
];

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtTagLibrary": [
    {
      "uuid": "17882854-44a7-4b2d-a2b1-b022846ac41d",
      "title": "Common Tags",
      "color": "#008000",
      "textcolor": "#ffffff",
      "readOnly": true,
      "children": [
        {
          "type": "plain",
          "title": "book",
          "description": "",
          "color": "#008000",
          "textcolor": "#ffffff"
        }
      ],
      "expanded": true
    }
  ]
}

</TabItem> </Tabs>

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, 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.

{
  "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:

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'],
};

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "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"]
  }
}

</TabItem> </Tabs>

Configuring custom search queries

TagSpaces Pro can be pre-configured with predefined search queries.

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
  },
];

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtSearches": [
    {
      "uuid": "2123",
      "title": "Some query name",
      "textQuery": "",
      "tagsAND": [
        { "title": "tag1" },
        { "title": "tag2" }
      ],
      "tagsOR": [],
      "tagsNOT": [
        { "title": "tag3" }
      ],
      "searchBoxing": "location",
      "searchType": "fuzzy",
      "forceIndexing": true,
      "currentDirectory": "/home/username/Documents",
      "fileTypes": ["md", "mdown", "txt", "html"],
      "lastModified": "past7Days",
      "fileSize": "sizeVerySmall",
      "tagTimePeriodFrom": 1622505600000,
      "tagTimePeriodTo": 1625090399999,
      "maxSearchResults": 100,
      "showUnixHiddenEntries": true
    }
  ]
}

</TabItem> </Tabs>

Configuring custom map tile servers

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.

window.ExtMapTileServers = [
  {
    "uuid": "94cc9977-8b66-4f07-806e-110ae0d6b30e", // an unique id of the map tile server
    "name": "Carto Light",
    "serverURL": "https://cartodb-basemaps-{s}.global.ssl.fastly.net/light_all/{z}/{x}/{y}.png",
    "serverInfo": "Map tiles by Carto, under CC BY 3.0. Data by OpenStreetMap, under ODbL." // Map attribution
  }
];

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtMapTileServers": [
    {
      "uuid": "94cc9977-8b66-4f07-806e-110ae0d6b30e",
      "name": "Carto Light",
      "serverURL": "https://cartodb-basemaps-{s}.global.ssl.fastly.net/light_all/{z}/{x}/{y}.png",
      "serverInfo": "Map tiles by Carto, under CC BY 3.0. Data by OpenStreetMap, under ODbL."
    }
  ]
}

</TabItem> </Tabs>

:::tip Some example map tile servers can be found in the OpenStreetMap Wiki. 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 or in MGRS formats.

window.ExtGeoTaggingFormat = "pluscodes";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtGeoTaggingFormat": "pluscodes"
}

</TabItem> </Tabs>

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.

window.ExtDefaultMapBounds = {
  southWest: { lat: 56, lng: -13 },
  northEast: { lat: 29, lng: 50 },
}

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtDefaultMapBounds": {
    "southWest": { "lat": 56, "lng": -13 },
    "northEast": { "lat": 29, "lng": 50 }
  }
}

</TabItem> </Tabs>

The geo coordinates in the example above are the default ones, will open Europe in the map.

{/* ## Configuring third-party extensions

window.ExtExtensionsFound = [
  {
    extensionId: '@tagspaces/arithmetic-player',
    extensionName: 'Mental Arithmetic',
    extensionTypes: ['viewer'],
    extensionEnabled: true,
    version: '1.0.0',
  },
];

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)

&lt;Tabs groupId=“config”>
  &lt;TabItem value=“js” label=“extconfig.js”>
```js
window.ExtDefaultVerticalPanel = "none";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtDefaultVerticalPanel": "none"
}

</TabItem> </Tabs>

Possible values: none, taglibrary, locations

Show welcome panel

window.ExtShowWelcomePanel = true;

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtShowWelcomePanel": true
}

</TabItem> </Tabs>

Possible values: true, false. Default value: true.

Show smart tags

Smart tags are documented [here](https://docs.tagspaces.org/ui/taglibrary/#smart-tags.

window.ExtShowSmartTags = true;

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtShowSmartTags": true
}

</TabItem> </Tabs>

Possible values: true, false. Default value: true.

Enable location based tags

The [location tags](https://docs.tagspaces.org/ui/taglibrary/#location-tags are saved in the location's folder and not centrally in the applicaiton's configuration.

window.ExtUseLocationTags = true;

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtUseLocationTags": true
}

</TabItem> </Tabs>

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.

window.ExtAuthor = 'Some name or abbreviation';

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtAuthor": "Some name or abbreviation"
}

</TabItem> </Tabs>

Hide PRO features

This setting provides a way to hide the PRO features, which make sense in the LITE version in order to reduce by visual complexity.

window.ExtHideProFeatures = true;

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtHideProFeatures": true
}

</TabItem> </Tabs>

Possible values: true, false. Default value: false.

Theming

Choose startup theme

window.ExtTheme = "dark";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtTheme": "dark"
}

</TabItem> </Tabs>

Possible values: dark, light.

Configuring perspectives

Perspectives are the different views available for the directory pane — Grid, List, Gallery, Mapique, Kanban, FolderViz, Calendar, plus any external perspectives shipped as packages. The settings below let deployers pre-select which perspective opens by default and restrict the set of perspectives the user can switch between.

Possible perspective IDs: grid, list, gallery, mapique, kanban, folderviz, calendar. External perspectives (shipped as packages under @tagspacespro/extensions/<name>) declare their own ID via the tsextension.id field in their package.json.

Open app with a predefined perspective

The ExtDefaultPerspective property pins which perspective is used as the initial view for newly opened folders that don't yet have a per-folder preference recorded in their .ts/tsm.json metadata. The user can still change the perspective interactively; this only sets the starting point for fresh folders.

window.ExtDefaultPerspective = "gallery";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtDefaultPerspective": "gallery"
}

</TabItem> </Tabs>

Default: grid.

Restricting the available perspectives

The ExtEnabledPerspectives property is a whitelist of perspective IDs that the application will expose to the user. When set:

The perspective switcher in the toolbar shows only the listed IDs.
The Settings → Perspectives tab renders the rows but the toggles become read-only with a “configured by your administrator” tooltip; any value the user previously persisted is overridden on every load.
IDs not present in the whitelist are hidden from the switcher even if they would normally appear (for example Pro perspectives in a Pro build).
Unknown IDs in the array are silently ignored.

window.ExtEnabledPerspectives = ["grid", "list", "kanban"];

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtEnabledPerspectives": ["grid", "list", "kanban"]
}

</TabItem> </Tabs>

:::tip Precedence: ExtEnabledPerspectives always wins over the user's own toggles. Removing the property from extconfig returns control to the user's persisted preferences. :::

When this property is not set, the user owns the toggles in the Settings → Perspectives tab and the switcher reflects whatever the user enabled there. The default state is “all built-in perspectives enabled“ plus any external perspectives the build includes.

Custom color for the default themes

Set custom light color for the light theme

window.ExtLightThemeLightColor = "#dcf3ec";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtLightThemeLightColor": "#dcf3ec"
}

</TabItem> </Tabs>

Possible value: any css color

Default value: '#dcf3ec'

Set custom main color for the light theme

window.ExtLightThemeMainColor = "#1dd19f";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtLightThemeMainColor": "#1dd19f"
}

</TabItem> </Tabs>

Possible value: any css color

Default value: '#1dd19f'

Set custom light color for the dark theme

window.ExtDarkThemeLightColor = "#56454e";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtDarkThemeLightColor": "#56454e"
}

</TabItem> </Tabs>

Possible value: any css color

Default value: '#56454e'

Set custom main color for the dark theme

window.ExtDarkThemeMainColor = "#ff9abe";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtDarkThemeMainColor": "#ff9abe"
}

</TabItem> </Tabs>

Possible value: any css color

Default value: '#ff9abe'

Set the default folder color

The ExtDefaultFolderColor property sets the accent color used for folders across the application — folder cells in the Grid, List, Kanban, Calendar, Mapique and FolderViz perspectives, as well as the folder icon in the title bar of the entry container.

window.ExtDefaultFolderColor = "#a466aa";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtDefaultFolderColor": "#a466aa"
}

</TabItem> </Tabs>

Possible value: any css color

Default value: '#a466aa'

:::tip When this property is set, the matching “Default folder color” picker in Settings → General becomes read-only — the deployer's value wins over any color the user previously chose. Removing the property from extconfig returns control to the user's persisted preference. :::

Custom prompts for AI functionalities

Default question prompt

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:";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "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:"
}

</TabItem> </Tabs>

Prompt for summary generation

window.ExtSummarizePrompt = "Generate a concise summary {max_chars} in {language} language for the following text: {summarize_text}";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtSummarizePrompt": "Generate a concise summary {max_chars} in {language} language for the following text: {summarize_text}"
}

</TabItem> </Tabs>

Prompt for generation of structured description for an image

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.";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "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."
}

</TabItem> </Tabs>

Prompt for generation of description for an image

window.ExtDescriptionFromImagePrompt = "Generate a concise description for this image {file_name} in {language} language.";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtDescriptionFromImagePrompt": "Generate a concise description for this image {file_name} in {language} language."
}

</TabItem> </Tabs>

Prompt for generation of description for text

window.ExtDescriptionFromTextPrompt = "Generate a concise description {max_chars} in {language} language for this text: {input_text}.";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtDescriptionFromTextPrompt": "Generate a concise description {max_chars} in {language} language for this text: {input_text}."
}

</TabItem> </Tabs>

Prompt for generating tags from image

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.";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtTagsFromImagePrompt": "Write the most important topics from the image description. The output TOPICS must be in parsable format like {keyword} without whitespace in braces."
}

</TabItem> </Tabs>

Prompt for generating tags from text

window.ExtTagsFromTextPrompt = "Extract important tags (single words please) and sort them by their importance from the following content: {input_text}";

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtTagsFromTextPrompt": "Extract important tags (single words please) and sort them by their importance from the following content: {input_text}"
}

</TabItem> </Tabs>

Custom templates for new files

Default new file template

window.ExtDefaultFileTemplate = {
  id: 'default',
  name: 'Default',
  content: '{createdInApp} ({date})',
  fileNameTmpl: 'note[{timestamp}]',
};

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtDefaultFileTemplate": {
    "id": "default",
    "name": "Default",
    "content": "{createdInApp} ({date})",
    "fileNameTmpl": "note[{timestamp}]"
  }
}

</TabItem> </Tabs>

Defining a set of templates for new files

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
  }]

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtFileTemplates": [
    {
      "id": "62342",
      "name": "External Template 1",
      "description": "Default template for new markdown files",
      "type": "md",
      "content": "{createdInApp} ({date}) by {author}",
      "fileNameTmpl": "task[{timestamp}]",
      "screenshotUrl": "dataURL:..."
    },
    {
      "id": "72323",
      "name": "External Template 2",
      "description": "Default template for new text files",
      "type": "txt",
      "content": "{createdInApp} ({date})",
      "fileNameTmpl": "issue[{timestamp}]",
      "screenshotUrl": "dataURL:..."
    }
  ]
}

</TabItem> </Tabs>

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.json file
Install TagSpaces.app to your Applications folder with simple drag and drop

Alternatively you can copy the extconfig.json 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.json in the extracted folder
Zip the folder and redistribute

Alternatively copy the extconfig.json directory to the installation folder, as shown in the following screenshot. The path is usually C:\Users\USERNAME\AppData\Local\Programs\TagSpaces.

{/ <CenteredImage caption=“Location of the extconfig.js in the Windows applcation's structure” src=“/media/setup/windows-extconfig.avif” maxWidth=“600px” showCaption /> /}

For Linux

Extract the content of TagSpaces' TAR.GZ package to a folder e.g. your desktop
Copy the extconfig.json in the extracted folder
Zip the folder and redistribute

Example configuration files

Here you will find the whole configuration file, so it can be easily copied and reused for your custom needs.

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",
      },
    ],
  },
];

</TabItem> <TabItem value=“json” label=“extconfig.json”>

{
  "ExtLogoURL": "https://www.tagspaces.org/content/text-logo.svg",
  "ExtIsFirstRun": false,
  "ExtTheme": "dark",
  "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
    }
  ],
  "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"
        }
      ]
    }
  ]
}

</TabItem> </Tabs>