Data Sources

Data sources available for use by the ICS community

Platforms

ICS supported platforms.

Teams

ICS Teams


Menu Button Menu Button

Working with Obsidian

This tutorial will guide you through setting up Obsidian for editing markdown-based documentation that is managed via a Git repository. We'll configure essential plugins, update settings, and outline best practices for managing changes efficiently.

Configuration

To make Obsidian more user-friendly for writing documentation, update these settings:

Setting Value
Confirm file deletion Enabled
Deleted files Move to system trash: Enabled
Automatically update internal links Enabled
Default location for new notes Same folder as current file
New link format Relative path to file
Use [[Wikilinks]] Disabled
Detect all file extensions Enabled
Default location for new attachments In subfolder under current folder
Subfolder name assets

Plugins

Obsidian supports community plugins that extend its functionality. To enable and install these plugins, follow these steps:

  1. In Obsidian, open Settings.
  2. Navigate to Community plugins.
  3. Disable Safe mode to allow plugin installation.
  4. Click Browse and search for the plugin you wish to install.

Git Plugin

The obsidian-git plugin integrates Git functionality directly into Obsidian. To install it:

  1. Follow the steps above to access the Community plugins area.
  2. Search for obsidian-git and click Install.
  3. Once installed, configure it as follows:

Settings for obsidian-git

Setting Value
Split automatic commit and push Enabled
Vault commit interval (minutes) 15
Auto Backup after stopping file edits Enabled
Auto commit after latest commit Disabled
Vault push interval (minutes) 15
Auto pull interval (minutes) 5
Specify custom commit message on auto backup Disabled
Commit message on auto backup/commit updating {{numFiles}} files
Commit message on manual backup/commit updating {{numFiles}} files
{{date}} placeholder format YYYY-MM-DD HH:mm:ss
{{hostname}} placeholder replacement Custom hostname per device
Preview commit message Disabled
List filenames affected by commit Enabled
Sync Method Merge
Pull updates on startup Enabled
Push on backup Enabled
Pull changes before push Enabled
Show commit authoring information Disabled
Automatically refresh Source Control View on file changes Enabled
Source Control View refresh interval 7000 (milliseconds)
Disable notifications Enabled
Hide notifications for no changes Disabled
Show status bar Enabled
Show stage/unstage button in file menu Enabled
Show branch status bar Enabled
Show the count of modified files in the status bar Disabled
Author name for commit <Your Name>
Author email for commit <Your Email Address>@wustl.edu

Advanced Settings

Ensure you configure Windows paths correctly for Custom Git binary path and Additional environment variables.

Paste Image Rename

The paste image rename plugin makes it easy to paste images into your documentation. It will drop the file into assets folder and give it a name based on the current document name.

Setting Value
Image name pattern {fileName}
Duplicated number at start (or end) Disabled
Duplicate number delimiter -
Always add duplicate number Disabled
Auto rename Enabled
Handle all attachments Disabled
Exclude extension pattern
Disable rename notice Enabled

Marp Slides

Set the Theme Path setting to infrastructure/documentation/assets/marp to enable the Wash U theme for your slide decks.

Other Plugins

Additional plugins such as Marp Slides for presentations and Copilot for AI assistance can also be explored as they become available.

Advanced Change Management

Best practices involve using a new branch for each set of changes. The following sections will describe the process of creating branches and managing your changes in a more traditional git workflow. Note that taking this approach may require that you disable the Vault Commit and Vault Push settings described above.

Creating a new branch

  1. Open the command palette (cmd + p or windows + p).
  2. Select Git: Create New Branch.
  3. Enter the branch name and press Enter.
  4. Click the Push button, select origin, and enter origin/<branch_name>.

Staging and Committing Changes

Note: If the Source Control View is not shown, you can enable it by opening the command palette and selecting Git: Open source control view. It sill then show in the right menu panel.

To stage and commit changes:

  1. Open the Source Control View.
  2. Review your changes and stage them by clicking the + button next to each file or click the Stage All button that is a circled + located on the top toolbar of this view.
  3. Enter or update the commit message (if needed) and press the Commit button (the checkmark on the top toolbar).

Pushing Changes

To push changes to the remote Git repository:

  1. Navigate to Source Control View.
  2. Press the Push button (the up arrow button on the toolbar) to update the remote repository with your local changes.

Submitting a Pull Request

Note: This cookbook will provide more information about submitting a pull request. Submitting a Pull Request

To submit a pull request in Azure DevOps:

  1. Navigate to the documentation repository in Azure DevOps. ics-documentation
  2. Click the Create a pull request button or select Pull requests from the left menu and then New pull request.
  3. Choose the branches for comparison and enter the details of your changes.
  4. Click Create to submit the pull request for review.

This setup ensures your documentation is easily manageable, version-controlled, and collaborative, empowering you to maintain high-quality, consistent documentation.

Table of Contents

Updated on August 7, 2025