In our mission to make Gistlyn an immensely useful and collaborative learning tool for exploring any .NET library, Gistlyn includes a streamlined UX for editing Collections making it easier than ever to create Live Docs which we believe is the best way to learn about a library, mixing documentation and providing a live development experience letting developers try out and explore what they've just learned without losing context by switching to their development environment and setting up new projects to match each code sample.
Gistlyn makes it easy to share C# snippets with colleagues or reporting an issue to library maintainers with just a URL or a saved Gist ID which anyone can view in a browser at gistlyn.com or on their Desktop version of Gistlyn.
Here's an example of the new Collection authoring features in action:
The best thing about Gistlyn collections are they're just plain Github Gist's with a single index.md
Markdown document. So if you've previously created documentation in Github or asked questions in StackOverflow
you already know how to create Github collections.
All documentation within Gistlyn including this and the Home page are Gistlyn Collections which can be viewed by clicking the Collections header icon:
The Collections icon opens the Home Collection by adding its Gist id to the ?collection query string:
When adding links in your collection you should only include the ?querystring portion and not the
absolute url, e.g http://gistlyn.com?collection=... so your links also work in
Desktop versions of Gistlyn
which are instead run from localhost:4000.
Creating a Collection can be done at anytime from Gistlyn's main menu:
This will open an Empty Markdown Document into the Markdown Editor.
Hit Ctrl+S to save your modified copy to your Github Gists. After saving, the top bar will
turn Green to indicate you're viewing or modifying one of your own Gists or Collections:
Once editing the document you can use the Markdown Toolbar to quickly access Markdown specific formatting features like the Insert Link icon:
Which opens the Insert Link dialog and quickly create and link to new Gist or Collection by selecting the existing Gist or Collection you wish to use as a template:
This lets you quickly create multiple C# Gists using a copy of an existing Gists packages.config and
supporting .cs source files, significantly reducing the effort for creating multiple C# samples.
You can add images to your document by click on the Insert Image icon below:
This will open the Insert Image dialog where you can drag multiple images to upload them to imgur and embed them in your document:
After each image has finished uploading to Imgur, it will be embedded in your document from your Cursors position using the Markdown Image Format below:
As you're authoring your Markdown Document you can freely jump between different Gists or Collections as Gistlyn automatically saves as-you-type so you can use the Back button to jump back to your new collection as you left it without missing a beat.
After navigating away from your page, the arrow icons shown below will appear in the middle to indicate what you're editing on the left no longer matches the same page on the right:
Use the top right arrow icon to load the page you're editing in the preview window on the right to load the real-time preview of your Markdown document.
Use the bottom left arrow icon to load the Collection you're viewing on the right in the Editor.
If manually linking to Gists, other Collections and Snapshots use the following formats below:
- Gists:
?gist={id} - Collections:
?collection={id} - Snapshots:
?snapshot={id}
When Gistlyn sees these links it loads them into your current Gistlyn session. All other links are handled by the browser which navigates to the specified URL causing a full page load. If you're linking to an external site outside of Gistlyn we recommend opening it in a new browser Window by using HTML instead of Markdown links. e.g:
<a target="_blank" href="http://example.org">name</a>
You can find all of Gistlyn's Collections as Gists under the Gistlyn Github Account. Looking through some of Gistlyn collections below and their Markdown sources should provide a good resource for learning how to create Collections in Markdown:
- Gistlyn Collections (this page) (source)
- Home (source)
- OrmLite Interactive Tour (source)
- Gistlyn Snapshots (source)
- Add ServiceStack Reference (source)
Instead of sending links with unmemorable gist ids, you can also request to have easier to remember URLs for links to any Gistlyn collection by leaving a comment on the Friendly Names Gist
Where any link in the above Gist are available to Gistlyn, so instead of publishing links to a long
?collection={id} URL, you can use a shorter and easier to remember name instead, e.g:
That like a URL shortener, redirects to the linked url: ?collection=991db51e44674ad01d3d318b24cf0934