| 1 | ## Using Smartdown to view Gists
|
| 2 |
|
| 3 | [GitHub Gist](https://help.github.com/articles/about-gists/) is a free service that provides a way to store one or more files, including Smartdown and image files. More importantly, the files within a Gist can be accessed by various other programs via HTTP. The Smartdown library is able to access content within a Gist, and is able to support relative navigation within a Gist.
|
| 4 |
|
| 5 | This feature is in its early stages, so the spec may change and there may be bugs.
|
| 6 |
|
| 7 | A Gist is identified by its *organization* and its *identifier*, which are usually written as `organization/identifier`. For example, the Gist we'll be using as an example below is identified as `DoctorBud/f77a59978b435d457d635c7a50468790`, where `DoctorBud` is the organization and `f77a59978b435d457d635c7a50468790` is the identifier. Together, this is the Gist *path* used to uniquely identify a Gist.
|
| 8 |
|
| 9 | ### Gist Tests
|
| 10 |
|
| 11 | For the following example, we'll be using the [Eugene parking visualization with Python and Smartdown](https://gist.github.com/DoctorBud/f77a59978b435d457d635c7a50468790) Smartdown Notebook, which contains several interlinked Smartdown cards stored as `.md` files within the Gist. We'll look at several different ways to view this same content.
|
| 12 |
|
| 13 |
|
| 14 | #### Basic GitHub Gist View
|
| 15 |
|
| 16 | When viewed via GitHub's Gist Viewer, it is possible to see all of the Smartdown files in the notebook, as well as some supporting files needed for `bl.ocks.org`. Note that the Smartdown is rendered as Markdown, and many of the Smartdown-specific features are not usable directly within GitHub.
|
| 17 |
|
| 18 | [`https://gist.github.com/DoctorBud/f77a59978b435d457d635c7a50468790`](https://gist.github.com/DoctorBud/f77a59978b435d457d635c7a50468790)
|
| 19 |
|
| 20 | #### `bl.ocks.org` View
|
| 21 |
|
| 22 | The [bl.ocks.org](https://bl.ocks.org) website works by rendering content stored in GitHub Gists, and with some preparation, can be used to view Smartdown content.
|
| 23 |
|
| 24 | `bl.ocks.org` provides two views:
|
| 25 |
|
| 26 | - A *source* view that renders content as well as displaying the source files: [`https://bl.ocks.org/DoctorBud/f77a59978b435d457d635c7a50468790`](https://bl.ocks.org/DoctorBud/f77a59978b435d457d635c7a50468790)
|
| 27 | - A *raw* view that displays only the rendered content. [`https://bl.ocks.org/DoctorBud/raw/f77a59978b435d457d635c7a50468790/#Home`](https://bl.ocks.org/DoctorBud/raw/f77a59978b435d457d635c7a50468790/#Home)
|
| 28 |
|
| 29 | Note the use of `/raw` to distinguish the two URLs.
|
| 30 |
|
| 31 |
|
| 32 | #### Smartdown `/lib` and '/gist' Usage
|
| 33 |
|
| 34 | The Smartdown Simple Site supports the use of the browser location *hash* to select particular Cards within a multicard notebook. This has been extended such that Gists can be referenced and loaded easily. There are two techniques I'm trying out, but both rely upon using the Gist path as the location hash to build a URL that will load the Gist content.
|
| 35 |
|
| 36 | ##### Pure URLs good for Bookmarking
|
| 37 |
|
| 38 | - [https://smartdown.site/#gist/doctorbud/f77a59978b435d457d635c7a50468790](https://smartdown.site/#gist/doctorbud/f77a59978b435d457d635c7a50468790)
|
| 39 | - [https://smartdown.site/lib/#gist/doctorbud/f77a59978b435d457d635c7a50468790](https://smartdown.site/lib/#gist/doctorbud/f77a59978b435d457d635c7a50468790)
|
| 40 | - [https://smartdown.site/gist/#doctorbud/f77a59978b435d457d635c7a50468790](https://smartdown.site/gist/#doctorbud/f77a59978b435d457d635c7a50468790)
|
| 41 |
|
| 42 |
|
| 43 | ##### Smartdown Tunnels
|
| 44 |
|
| 45 | Smartdown Tunnels are a form of hyperlink that replaces the Smartdown content while leaving the Smartdown container intact and preserving the state of the Smartdown environment (i.e., variables).
|
| 46 |
|
| 47 | - [:@gist/doctorbud/f77a59978b435d457d635c7a50468790](:@gist/doctorbud/f77a59978b435d457d635c7a50468790)
|
| 48 | - [:@/gist/#doctorbud/f77a59978b435d457d635c7a50468790](:@/gist/#doctorbud/f77a59978b435d457d635c7a50468790)
|
| 49 |
|
| 50 | ---
|
| 51 |
|
| 52 | [Back to Home](:@Home)
|
| 53 |
|
| 54 |
|