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.
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.
- Save notes from Obsidian as public or secret gists
- Manual and autosave settings available
- Requires Github Personal Access Token (free).
- 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
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:
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
This option displays gists in a codeblock with line numbers, and the text of the gist.
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.
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.
To embed a snippet from Github or OpenGist, add a new code block:
```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
```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:
The following instructions explain how to install this plugin for Obsidian.
-
Install Obsidian.md
-
Go to the Releases tab in this Github repo, and download the associated files:
main.jsmanifest.jsonstyles.css- all releases also include a
.zipwith 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
Gistrand enable it.
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.
Instructions for building various aspects of 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:
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-pluginChange over to the docs/ directory.
cd docs/To build your mkdocs documentation, type:
mkdocs buildTo start mkdocs and serve the documentation locally (IF you are not using the Mike plugin), run
mkdocs serveOr you can start mkdocs with the --clean argument:
mkdocs serve --cleanYou 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 serveTo 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]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"
}- 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.
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:
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:
