[![Version][github-version-img]][github-version-uri] [![Build Status][github-build-img]][github-build-uri] [![Downloads][github-downloads-img]][github-downloads-uri] [![Size][github-size-img]][github-size-img] [![Last Commit][github-commit-img]][github-commit-img] ![Contributors][contribs-all-img]

---

• About
• Features
  • Methods:
    • Method 1: Codeblock
    • Method 2: Integrated Browser
  • Convert Note to Gist:
• Usage
  • Github Gist
  • OpenGist
• Install
  • Manual
  • BRAT Plugin Manager
• Build
  • Gistr
  • Documentation
• OpenGist - How It Works
• Shoutouts
  • Contributors ✨

---

About

The following is an outline of what Gistr can do for you:

Supported Services:

• Github Gists
• OpenGist Server
• As of v1.6.x: Any website

Functionality:

• Two modes for embedding: Codeblock mode and Website mode.
• (Website Mode): Embed any website into your Obsidian notes. Fully functioning browser with ability to sign in to accounts and navigate.
  • Can be used for Github / Gist mermaid graphs
  • Activated with raw property
  • raw property supports the ability to specify additional properties:
    • zoom: change the size of the website
    • height: change the height of the website frame
    • css: override existing CSS on the embedded website
• Save notes from Obsidian as public or secret gists
  • Manual and autosave settings available
  • Requires Github Personal Access Token (free).
    • Click here to read setup instructions
• Line numbering & syntax highlighting
• Open embedded Github Gist or Opengist snippets from your notes in your device browser
• Filter out gists that contain more than one file
• Enable / Disable text wrapping and horizontal scrollbar
• Fast performance and caching
• Complete customization for almost every aspect of the plugin and the sites you embed

Themes:

• Includes Light & Dark themes for Github and Opengist
• Customize individual colors through Gistr settings, or use CSS stylesheet override
• Thin and customizable scrollbar
• Force amy theme on each individual gist paste

---

Features

This section gives a brief explanation of what Gistr can do. Please note that the list below is very minimal and does not cover everything the plugin can do. To view a full feature list; read the documentation:

• Docs: Basic Usage
• Docs: Properties List

Methods:

As of version 1.6.0, Gistr now includes two ways to integrate gists into your obsidian.md notes.

• Method 1: Codeblocks
• Method 2: Integrated Browser

Method 1: Codeblock

This option displays gists in a codeblock with line numbers, and the text of the gist.

Method 2: Integrated Browser

This option displays gists in a browser-like environment. It allows you to sign into Github or your Opengist site and view / edit your gists.

Convert Note to Gist:

This feature allows you to take notes in your Obsidian vault and upload them as gists to Github or Opengist.

After writing your note in Obsidian, right-click anywhere in your note and select Save Gist, then choose the type: public or secret.

If you have already uploaded an Obsidian note as a gist, you can update the gist right from Obsidian. Either manually save, or allow the plugint o automatically update your gist every x minutes (can be changed in the plugin settings).

[!NOTE]

To convert your notes into gists, you must register for a Personal Access Token on Github.

---

Usage

To embed a snippet from Github or OpenGist, add a new code block:

Github Gist

```gistr
url:    https://gist.github.com/username/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

This plugin can also fetch a Gist which contains multiple notes in a single collection. If your gist contains multiple files, you can target a specific note to show by using the file property:

```gistr
url:    https://gist.github.com/Aetherinox/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
file:   file1
```

If you do not target a specific file on a gist which contains multiple files, all files with that matching URL will be displayed on top of each other.

You can force an individual gist to use a specific theme. You may choose the theme dark or light:

```gistr
url:    https://gist.github.com/Aetherinox/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
theme:  dark
```

OpenGist

Showing gists from your OpenGist server work in a similar manner to Github. To display gists from OpenGist, create a new codeblock and add your gist URL:

```gistr
url:    https://gist.yourdomain.com/username/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

You can force an individual gist to use a specific theme. You may choose the theme dark or light:

url:    https://gist.yourdomain.com/Username/Gist_ID
theme:  light

To use Opengist, you must install the program on your system as a service, or you can rent a web server. To view a demo of Opengist, as well as full documentation; visit the links below:

---

Install

The following instructions explain how to install this plugin for Obsidian.

Manual

• Install Obsidian.md

• Go to the Releases tab in this Github repo, and download the associated files:

  • main.js
  • manifest.json
  • styles.css
  • all releases also include a .zip with the files above.

• Locate your Obsidian Plugins Folder X:\.obsidian\plugins

• Create new folder in Plugins folder labeled gistr

• Inside the new folder, paste the files you have downloaded from this Github repo.

📂 .obsidian
   📂 plugins
      📂 gistr
         📄 main.js
         📄 manifest.json
         📄 styles.css

• Launch Obsidian and click the Settings Cog Icon ⚙️
• On the left, select Community Plugins
• Locate Gistr and enable it.

BRAT Plugin Manager

Plugin can also be installed utilizing the BRAT plugin.

• Install BRAT using the Obsidian Plugin manager
• In your Obsidian settings on the left, select BRAT in the list.
• In BRAT settings, click the button Add Beta Plugin
• In the textbox, supply the URL to this repo
  • https://github.com/Aetherinox/obsidian-gistr
• Once Gistr is installed, activate it in your Obsidian settings.

---

Build

Instructions for building various aspects of Gistr:

Gistr

For a detailed set of instructions on how to download this plugin's source files and compile your own version, check out the wiki link below:

• How to Build Gistr

Documentation

This project uses mkdocs for its documentation.

To install mkdocs and the required plugins:

pip install mkdocs
pip install mkdocs-material
pip install mike
pip install mkdocs-encryptcontent-plugin
pip install mkdocs-git-committers-plugin-2
pip install mkdocs-glightbox
pip install mkdocs-material
pip install mkdocs-redirects
pip install pymdown-extensions
pip install mkdocs-git-revision-date-localized-plugin
pip install mkdocs-git-authors-plugin
pip install mkdocs-exclude-search
pip install mkdocs-minify-plugin

Change over to the docs/ directory.

cd docs/

To build your mkdocs documentation, type:

mkdocs build

To start mkdocs and serve the documentation locally (IF you are not using the Mike plugin), run

mkdocs serve

Or you can start mkdocs with the --clean argument:

mkdocs serve --clean

You will then be able to access your documentation by opening your browser and going to:

http://127.0.0.1:8000/