Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/aetherinox/obsidian-gistr

Obsidian.md plugin which allows you to use your notes to embed, create, and update gists for Github and Opengist. Light & dark theme support, create / update public & private gists either manually or with autosave.
https://github.com/aetherinox/obsidian-gistr

gist gists javascript nodejs obsidian obsidian-community obsidian-md obsidian-notes obsidian-plugin obsidian-plugin-development obsidian-plugins obsidian-publish obsidian-vault obsidianmd opengist typescript

Last synced: about 2 months ago
JSON representation

Obsidian.md plugin which allows you to use your notes to embed, create, and update gists for Github and Opengist. Light & dark theme support, create / update public & private gists either manually or with autosave.

Awesome Lists containing this project

README 

        


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.























[![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]](#contributors-)










---







- [About](#about)

- [Features](#features)

  - [Methods:](#methods)

    - [Method 1: Codeblock](#method-1-codeblock)

    - [Method 2: Integrated Browser](#method-2-integrated-browser)

  - [Convert Note to Gist:](#convert-note-to-gist)

- [Usage](#usage)

  - [Github Gist](#github-gist)

  - [OpenGist](#opengist)

- [Install](#install)

  - [Manual](#manual)

  - [BRAT Plugin Manager](#brat-plugin-manager)

- [Build](#build)

  - [Gistr](#gistr)

  - [Documentation](#documentation)

- [OpenGist - How It Works](#opengist---how-it-works)

- [Shoutouts](#shoutouts)

  - [Contributors ✨](#contributors-)







---







# About

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







**Supported Services**:

- [Github Gists](https://gist.github.com)

- [OpenGist Server](https://github.com/thomiceli/opengist)

- _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](https://aetherinox.github.io/obsidian-gistr/usage/properties/#raw) property

  - [raw](https://aetherinox.github.io/obsidian-gistr/usage/properties/#raw) property supports the ability to specify additional properties:

    - [zoom](https://aetherinox.github.io/obsidian-gistr/usage/properties/#property-zoom): change the size of the website

    - [height](https://aetherinox.github.io/obsidian-gistr/usage/properties/#property-height): change the height of the website frame

    - [css](https://aetherinox.github.io/obsidian-gistr/usage/properties/#property-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](https://github.com/settings/tokens?type=beta) (free).

    - [Click here to read setup instructions](https://aetherinox.github.io/obsidian-gistr/settings/github/)

- 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](https://aetherinox.github.io/obsidian-gistr/usage/basic/)

- [Docs: Properties List](https://aetherinox.github.io/obsidian-gistr/usage/properties/)







## Methods:

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



- Method 1: [Codeblocks](#method-1-codeblock)

- Method 2: [Integrated Browser](#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](https://github.com/settings/tokens?type=beta) on Github.







---







# Usage

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







## Github Gist



````shell

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



````shell

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



````shell

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







````shell

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







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










[![OG-Demo](https://img.shields.io/badge/%20-%20Try%20%20OpenGist%20Demo-%20%236c2368?style=for-the-badge&logo=github&logoColor=FFFFFF)](https://demo.opengist.io/all)

[![OG-Download](https://img.shields.io/badge/%20-%20Download%20OpenGist-%20%23de2343?style=for-the-badge&logo=github&logoColor=FFFFFF)](https://github.com/thomiceli/opengist/releases)

[![OG-Docs](https://img.shields.io/badge/%20-%20View%20%20OpenGist%20Docs-%20%23296ca7?style=for-the-badge&logo=github&logoColor=FFFFFF)](https://github.com/thomiceli/opengist/blob/master/docs/index.md)










---







# Install

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







## Manual



- Install [Obsidian.md](obsidian.md/)

- Go to the [Releases](https://github.com/Aetherinox/obsidian-gistr/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](https://github.com/TfTHacker/obsidian42-brat) plugin.

- Install [BRAT](https://github.com/TfTHacker/obsidian42-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](https://aetherinox.github.io/obsidian-gistr/advanced/build/)







## Documentation

This project uses [mkdocs]() for its documentation.







To install mkdocs and the required plugins:

```shell ignore

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. 



```shell ignore

cd docs/

```







To build your mkdocs documentation, type:

```shell ignore

mkdocs build

```







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

```shell ignore

mkdocs serve

```







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

```shell ignore

mkdocs serve --clean

```







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

```shell ignore

http://127.0.0.1:8000/

```







If using the **[Mike](https://github.com/jimporter/mike)** plugin. The Mike plugin allows you to manage multiple versions of your MkDocs-powered documentation via Git  



```shell ignore

mike serve

```







To deploy with Mike:

```shell ignore

mike deploy [version]

mike deploy [version] [alias]...

```







To display versions with Mike:

```shell ignore

mike list

mike list [identifier]

```







To set the default version for Mike:

```shell ignore

mike set-default [identifier]

```







Changing a version title for Mike:

```shell ignore

mike retitle [identifier] [title]

```







---







# OpenGist - How It Works

The following explains the procedure behind this plugin and OpenGist.



As of v1.6.0, [OpenGist](https://github.com/thomiceli/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:



```json

{

  "created_at": "2023-09-24T00:00:000",

  "description": "Opengist Demo Paste",

  "embed": {

    "css": "https://gist.domain.com/assets/embed-abcde123.css",

    "html": "
\n    
\n    \n        
\n            
\n                Opengist Demo Paste · 145 B · Text\n                Hosted via Opengist · view raw\n            
\n            \n            \n            \n            
\n            \n            \n                \n                    \n                        \n                        \n                        1Opengist Demo Paste\n\n                    \n                \n            \n            
\n            \n\n        
\n    \n    
\n
\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](https://github.com/thomiceli)  over at [OpenGist](https://github.com/thomiceli/opengist) for implementing the JSON functionality request.

- [linjunpop](https://github.com/linjunpop) for developing the first Obsidian [Gist](https://github.com/linjunpop/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](.github/PULL_REQUEST_TEMPLATE.md)

- [Contributor Policy](CONTRIBUTING.md)







Want to help but can't write code?

- Review [active questions by our community](https://github.com/Aetherinox/obsidian-gistr/labels/help%20wanted) and answer the ones you know.







The following people have helped get this project going:










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



  

    

      Aetherinox
Aetherinox
💻 📆 🔍

    

  













  [general-npmjs-uri]: https://npmjs.com

  [general-nodejs-uri]: https://nodejs.org

  [general-npmtrends-uri]: http://npmtrends.com/obsidian-gistr



  [github-version-img]: https://img.shields.io/github/v/tag/Aetherinox/obsidian-gistr?logo=GitHub&label=Version&color=ba5225

  [github-version-uri]: https://github.com/Aetherinox/obsidian-gistr/releases



  [npm-version-img]: https://img.shields.io/npm/v/obsidian-gistr?logo=npm&label=Version&color=ba5225

  [npm-version-uri]: https://npmjs.com/package/obsidian-gistr



  [pypi-version-img]: https://img.shields.io/pypi/v/obsidian-gistr-plugin

  [pypi-version-uri]: https://pypi.org/project/obsidian-gistr-plugin/



  [license-mit-img]: https://img.shields.io/badge/MIT-FFF?logo=creativecommons&logoColor=FFFFFF&label=License&color=9d29a0

  [license-mit-uri]: https://github.com/Aetherinox/obsidian-gistr/blob/main/LICENSE



  [github-downloads-img]: https://img.shields.io/github/downloads/Aetherinox/obsidian-gistr/total?logo=github&logoColor=FFFFFF&label=Downloads&color=376892

  [github-downloads-uri]: https://github.com/Aetherinox/obsidian-gistr/releases



  [npmjs-downloads-img]: https://img.shields.io/npm/dw/%40aetherinox%2Fmkdocs-link-embeds?logo=npm&&label=Downloads&color=376892

  [npmjs-downloads-uri]: https://npmjs.com/package/obsidian-gistr



  [github-size-img]: https://img.shields.io/github/repo-size/Aetherinox/obsidian-gistr?logo=github&label=Size&color=59702a

  [github-size-uri]: https://github.com/Aetherinox/obsidian-gistr/releases



  [npmjs-size-img]: https://img.shields.io/npm/unpacked-size/obsidian-gistr/latest?logo=npm&label=Size&color=59702a

  [npmjs-size-uri]: https://npmjs.com/package/obsidian-gistr



  [codecov-coverage-img]: https://img.shields.io/codecov/c/github/Aetherinox/obsidian-gistr?token=MPAVASGIOG&logo=codecov&logoColor=FFFFFF&label=Coverage&color=354b9e

  [codecov-coverage-uri]: https://codecov.io/github/Aetherinox/obsidian-gistr



  [contribs-all-img]: https://img.shields.io/github/all-contributors/Aetherinox/obsidian-gistr?logo=contributorcovenant&color=de1f6f&label=contributors

  [contribs-all-uri]: https://github.com/all-contributors/all-contributors



  [github-build-img]: https://img.shields.io/github/actions/workflow/status/Aetherinox/obsidian-gistr/npm-release.yml?logo=github&logoColor=FFFFFF&label=Build&color=%23278b30

  [github-build-uri]: https://github.com/Aetherinox/obsidian-gistr/actions/workflows/npm-release.yml



  [github-build-pypi-img]: https://img.shields.io/github/actions/workflow/status/Aetherinox/obsidian-gistr/release-pypi.yml?logo=github&logoColor=FFFFFF&label=Build&color=%23278b30

  [github-build-pypi-uri]: https://github.com/Aetherinox/obsidian-gistr/actions/workflows/pypi-release.yml



  [github-tests-img]: https://img.shields.io/github/actions/workflow/status/Aetherinox/obsidian-gistr/npm-tests.yml?logo=github&label=Tests&color=2c6488

  [github-tests-uri]: https://github.com/Aetherinox/obsidian-gistr/actions/workflows/npm-tests.yml



  [github-commit-img]: https://img.shields.io/github/last-commit/Aetherinox/obsidian-gistr?logo=conventionalcommits&logoColor=FFFFFF&label=Last%20Commit&color=313131

  [github-commit-uri]: https://github.com/Aetherinox/obsidian-gistr/commits/main/