README file from
GithubObsidian Trello
Overview
Connect your Trello cards with your Obsidian notes to see and update labels, comments, and checklists from within Obsidian. There are plenty of features on the horizon and you can track progress on the Trello board for the project.
Use
Once installed and set up with a Trello API token (see prerequisites below) you can connect a card to a note.
Open the Trello Pane
If the Trello pane is not automatically opened, use the Show Trello view command and it will be created.
Connecting Cards
To connect a card to a note either use the Connect Trello card command or click the 'Connect Trello Card' button in the Trello Pane. If a card is already connected, there is a button to link a different card instead.
Creating new cards
When connecting a card, after selecting the Trello board you want to use, select 'Create a new card...'.
Refreshing Cards
The plugin does not poll or listen for updates from Trello, so changes made in Trello may not be immediately reflected in Obsidian. If you believe a card is out of date, click the refresh button. Data is cached for anywhere from one minute to ten minutes depending on the type of data. If you wish to forcibly refresh the entire cache, you can use the 'Reload app without saving' command.
Do be mindful that Trello's REST API has strict rate limits. If you run into any rate limiting issues please contact me so I can work on a fix.
Viewing Your Assigned Cards
Use the Show my Trello cards command to open a separate view of every open Trello card assigned to you. Cards can be grouped by board or sorted by due date. This view fetches your cards, boards, and open lists when it opens and whenever you click refresh; it does not poll Trello in the background.
Linking Multiple Cards
Enable Multiple cards per note (experimental) to link more than one Trello card to a Markdown note. The first card remains in the trello_board_card_id frontmatter property for compatibility, while additional cards are stored as a list in trello_cards. Each value has the form boardId;cardId.
Turning the setting off does not delete additional links; it hides them and makes newly linked cards replace the primary card. Re-enable the setting to show the additional links again. When several cards are visible, the disconnect command lets you unlink one card or all cards.
Disconnecting Cards
If you want to remove the connection between a note and a Trello card, click the 'Unlink card' button or use the Disconnect Trello card command. Prefer the button or command because it also cleans up the plugin's saved connection data. For a complete manual unlink, remove trello_plugin_note_id, trello_board_card_id, and trello_cards from the YAML frontmatter.
Moving cards between lists
A card can be moved to a new list by clicking on the list name.
Adding comments
New comments can be added from within Obsidian. It will appear at the top of the list as the most recent comment.
Checklists
Checking or unchecking an item in a checklist makes the corresponding change on the Trello card.
Customizing UI
If your workflow doesn't include comments or labels, for example, you can disable them in obsidian. Each UI element can be toggled on or off. This can be global, for all connected cards, using the 'Customize UI' option in plugin settings. Or, this can be managed for an individual note using the gear icon.
Setup
Prerequisites
- A Trello account
- A Trello API token (see below).
Before you can connect a Trello card, you need to create an API token and set it in the plugin settings. You can create a token here; make sure to copy it before closing the tab.
Tokens can be revoked at any time in your Trello account settings.
Settings
Trello Token - See the prerequisites above. This is required.
Customize UI - Adjust which parts of a card are displayed. This setting can be updated globally, which applies to all cards, and overridden on an individual note.
Select Boards - Filter the boards available to select cards from. If none are selected, all boards will be available.
Open to Side - Whether to open the Trello view to the left or right by default.
New Card Position - Whether newly created cards should be added to the top or bottom of the list by default. Can be overridden when adding a card.
Moved Card Position - When moving a card from one list to another, should it be moved to the top or bottom of the selected list.
Follow Moved Cards - Keep a note linked when its Trello card moves to another board. When the card is next loaded, the plugin updates the board ID stored in the note. Disable this to retain the previous board-scoped lookup behavior.
Multiple Cards Per Note (experimental) - Allow a Markdown note to display more than one linked card. Additional links are stored in the trello_cards frontmatter property.
Verbose Logging - Enable this if you're having trouble with the plugin. Logs will be enabled in the console. These can help me diagnose issues.
Commands
Show Trello view - Open the Trello pane, if it isn't already.
Show my Trello cards - Open the view of all open Trello cards assigned to you.
Connect Trello card - Connect a note to a (new) Trello card. Optionally, create a new Trello card.
Disconnect Trello card - Remove the Trello connection from a note.
Security and Privacy
The Trello token grants the plugin the read/write access requested on the authorization page. Obsidian stores it locally with the plugin settings, and the plugin sends it to Trello's HTTPS API as an authentication query parameter. Treat the token as a password: do not commit or share the plugin's data.json, screenshots of the token field, request URLs, or unredacted diagnostic logs. Revoke the token from your Trello account if it may have been exposed.
Card names, descriptions, comments, labels, board names, and list names are loaded from Trello for display in Obsidian. The My Trello cards view additionally requests all open cards assigned to the authenticated Trello user, along with their boards and open lists.
Theming
Wherever possible, the plugin uses built-in theme variables, so your color variable overrides will apply here. The exception is the trello colors included in the plugin; these match the colors from Trello's UI. However, these can be overridden the same as Obsidian's color variables. See variables.scss for the full listing of colors. Each has a base shade, lighter shade, and darker shade.
Is the plugin incompatible with a custom theme? Let me know and I'll look into updating the plugin or contributing to the theme to fix it.
Contributing
Pull requests are always welcome. Keep in mind that this plugin makes heavy use of rxjs for reactive state management.
Support
Raise an issue here on GitHub if there's a problem. If you're unsure, feel free to contact me on the Obsidian discord, @nathan.smith.