Obsidian.md Plugin

♾️ Gistr ♾️

A plugin for Obsidian.md which allows you to create, convert, and update notes from Obsidian to Github or Opengist. As well as integrate fully functional websites into your notes.

• 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

<br />

<p align="center"><img style="width: 85%;text-align: center;border: 1px solid #353535;" src="https://github.com/Aetherinox/obsidian-gistr/assets/118329232/062f2dc0-c14a-4d4f-a3e0-5358458a528a"></p>

<br />

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:

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

<br />

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.

<br />

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

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

<br />

<br />

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

<br />

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

<br />

<p align="center"><img style="width: 85%;text-align: center;border: 1px solid #353535;" src="https://github.com/Aetherinox/obsidian-gistr/assets/118329232/3e396b9f-7b31-4e9c-8557-2d6276c9afaa"></p>

<br />

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

<br />

```shell
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/

If using the Mike plugin. The Mike plugin allows you to manage multiple versions of your MkDocs-powered documentation via Git

mike serve

To deploy with Mike:

mike deploy [version]
mike deploy [version] [alias]...

To display versions with Mike:

mike list
mike list [identifier]

To set the default version for Mike:

mike set-default [identifier]

Changing a version title for Mike:

mike retitle [identifier] [title]

OpenGist - How It Works

The following explains the procedure behind this plugin and OpenGist.

As of v1.6.0, OpenGist includes a feature which works much like Github. Every time you upload a new gist to your OpenGist website, you can view that gist normally by going to the associated link:

https://gist.yourdomain.com/username/000abcdef1234567abcdef1234567abc

With OpenGist, you may now fetch JSON information about a gist, and include your gist in outside programs such as Obsidian.md.

To manually view the JSON, HTML, Javascript, and CSS feeds for each of your OpenGists, append .json to the end of your URL:

https://gist.yourdomain.com/username/000abcdef1234567abcdef1234567abc.json

You will be presented with JSON which defines the values associated to your created gist:

{
  "created_at": "2023-09-24T00:00:000",
  "description": "Opengist Demo Paste",
  "embed": {
    "css": "https://gist.domain.com/assets/embed-abcde123.css",
    "html": "<div class=\"opengist-embed\" id=\"000abcdef1234567abcdef1234567abc\">\n    <div class=\"html \">\n    \n        <div class=\"rounded-md border-1 border-gray-100 dark:border-gray-800 overflow-auto mb-4\">\n            <div class=\"border-b-1 border-gray-100 dark:border-gray-700 text-xs p-2 pl-4 bg-gray-50 dark:bg-gray-800 text-gray-400\">\n                <a target=\"_blank\" href=\"https://gist.domain.com/Username/000abcdef1234567abcdef1234567abc#file-demo\"><span class=\"font-bold text-gray-700 dark:text-gray-200\">Opengist Demo Paste</span> · 145 B · Text</a>\n                <span class=\"float-right\"><a target=\"_blank\" href=\"https://gist.domain.com\">Hosted via Opengist</a> · <span class=\"text-gray-700 dark:text-gray-200 font-bold\"><a target=\"_blank\" href=\"https://gist.domain.com/Username/000abcdef1234567abcdef1234567abc/raw/HEAD/demo_file.md\">view raw</a></span></span>\n            </div>\n            \n            \n            \n            <div class=\"code dark:bg-gray-900\">\n            \n            \n                <table class=\"chroma table-code w-full whitespace-pre\" data-filename-slug=\"demo\" data-filename=\"demo\" style=\"font-size: 0.8em; border-spacing: 0; border-collapse: collapse;\">\n                    <tbody>\n                        \n                        \n                        <tr><td id=\"file-demo-1\" class=\"select-none line-num px-4\">1</td><td class=\"line-code\">Opengist Demo Paste\n</td></tr>\n                    </tbody>\n                </table>\n            \n            </div>\n            \n\n        </div>\n    \n    </div>\n</div>\n",
    "js": "https://gist.domain.com/Username/000abcdef1234567abcdef1234567abc.js",
    "js_dark": "https://gist.domain.com/Username/000abcdef1234567abcdef1234567abc.js?dark"
  },
  "files": [
    {
      "filename": "demo",
      "size": 743,
      "human_size": "145 B",
      "content": "Opengist Demo Paste",
      "truncated": false,
      "type": "Text"
    }
  ],
  "id": "000abcdef1234567abcdef1234567abc",
  "owner": "Username",
  "title": "Opengist Demo Paste",
  "uuid": "000abcdef1234567abcdef1234567abc",
  "visibility": "unlisted"
}

Shoutouts

• thomiceli over at OpenGist for implementing the JSON functionality request.
• linjunpop for developing the first Obsidian Gist plugin. It was a top choice in my list of plugins used.

Contributors ✨

We are always looking for contributors. If you feel that you can provide something useful to Gistr, then we'd love to review your suggestion. Before submitting your contribution, please review the following resources:

• Pull Request Procedure
• Contributor Policy

Want to help but can't write code?

• Review active questions by our community and answer the ones you know.

The following people have helped get this project going:

[![Contributors][contribs-all-img]](#contributors-)

Aetherinox 💻 📆 🔍