Repository files navigation

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 ✨

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 andWebsite 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 withraw 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 GithubPersonal 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:

• IncludesLight &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:

• Docs: Basic Usage
• Docs: Properties List

As of version1.6.0, Gistr now includestwo 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 selectSave Gist, then choose the type:public orsecret.

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).

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

```gistrurl:    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 thefileproperty:

```gistrurl:    https://gist.github.com/Aetherinox/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxfile:   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 themedark orlight:

```gistrurl:    https://gist.github.com/Aetherinox/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxtheme:  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:

```gistrurl:    https://gist.yourdomain.com/username/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx```

You can force an individual gist to use a specific theme. You may choose the themedark orlight:

url:    https://gist.yourdomain.com/Username/Gist_IDtheme:  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.

• InstallObsidian.md

• Go to theReleases 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 FolderX:\.obsidian\plugins

• Create new folder inPlugins folder labeledgistr

• 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, selectCommunity Plugins
• LocateGistr and enable it.

Plugin can also be installed utilizing theBRAT plugin.

• InstallBRAT using the Obsidian Plugin manager
• In your Obsidian settings on the left, selectBRAT in the list.
• In BRAT settings, click the buttonAdd 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:

• How to Build Gistr

This project usesmkdocs for its documentation.

To install mkdocs and the required plugins:

pip install mkdocspip install mkdocs-materialpip install mikepip install mkdocs-encryptcontent-pluginpip install mkdocs-git-committers-plugin-2pip install mkdocs-glightboxpip install mkdocs-materialpip install mkdocs-redirectspip install pymdown-extensionspip install mkdocs-git-revision-date-localized-pluginpip install mkdocs-git-authors-pluginpip install mkdocs-exclude-searchpip install mkdocs-minify-plugin

Change over to thedocs/ 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 theMike 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 listmike 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 fetchJSON 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 atOpenGist for implementing the JSON functionality request.
• linjunpop for developing the first ObsidianGist 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:

• Pull Request Procedure
• Contributor Policy

Want to help but can't write code?

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

The following people have helped get this project going:

Aetherinox 💻📆🔍