A guide to Markdown publishing using the open source Docsify-This.net project.
Markdown is a markup language used to format the display of content stored as plain text - similar but simpler than HTML formatting
- System-independent
- Text only format (perfect for version control)
- Separation of content vs. presentation
- Human-readable (i.e. more than HTML)
- Can also contain HTML snippets
- Large number of editor and publishing apps
# Your H1 Text Here
## Your H2 Text Here
_your italic text here_
**your bold text here**
* your unordered list item here
1. your numbered (and indented) list item here
[link title](https://www.google.com)
Tip: To ensure a new paragraph after text in markdown, put two spaces after the end of the line
Looking for a more detailed overview of Markdown? Check out the Markdown Cheat Sheet – How to Write in Markdown with Examples.
- Markdown Converters
- For example, Pandoc
- Markdown Static Site Builders
- For example, Jekyll
- Markdown Dynamic Renderers
- For example, Docsify
Docsify-This is an open source Web app, built using the Docsify Open Publishing Kit, that can quickly display online Markdown files as web pages (i.e. no file uploads or build processes).
Being open source, you can also host your own Docsify-This instance, with the possibility of even a custom domain! No platform lock-in here.
- Publish your Markdown files as standalone web pages, with no website setup or build process required
- Visually style your standalone web pages using a point-and-click Web Page Builder
- Share existing GitHub-hosted Markdown files as standalone web pages, with an optional 'Edit this Page' link
- Seamlessly embed constraint-free Markdown/HTML into other platforms (e.g. LMS or CMS)
- Utilize the supported URL parameters when embedding content to match each destination platform better visually
To use the Docsify-This Web Page Builder enter the URL for an online Markdown file and tap the ‘Publish as Standalone Web Page’ button. The Markdown file will then be rendered as a standalone Web page with it’s own URL that can then be copied and shared.
Figure 1. Docsify-This Web Page Builder
https://docsify-this.net/?basePath=https://raw.githubusercontent.com/hibbitts-design/docsify-this-one-page-article/main&homepage=home.md
Figure 2. Docsify-This Rendered Markdown File
Docsify-This rendered Web pages are also perfect for embedding, with the ability to visually style Docsify-This pages to the destination platform.
You can also render other Markdown files in the same repository by manualy editing the Docsify-This URL parameter homepage, for example:
https://docsify-this.net/?basePath=https://raw.githubusercontent.com/hibbitts-design/docsify-this-one-page-article/main&homepage=anotherfile.mdThe visual appearance of any Markdown file displayed by Docsify-This can be altered with the Web Page Builder or using the provided set of URL Parameters. For example, font-family, font-size, link-color and line-height
https://docsify-this.net/?basePath=https://raw.githubusercontent.com/hibbitts-design/docsify-this-one-page-article/main&homepage=home.md&font-family=Open%20Sans,sans-serif
Please note that when you use the Docsify-This Web Page Builder the Docisfy-This URL generated includes these same URL parameters.
If you can edit the Markdown file that is displayed by Docsify-This the visual appearance can be further altered by using a set of provided Markdown CSS Classes. For example:
button
Required Reading Quiz due Jun 4th
[Required Reading Quiz due Jun 4th](https://canvas.sfu.ca/courses/44038/quizzes/166553 ':class=button')banner-image
In addition to the Markdown CSS classes supported by Docsify-This, you can also define your own custom classes within your displayed Markdown files, for example:
CSS in Markdown file:
<style>
.markdown-section .mybutton, .markdown-section .mybutton:hover {
cursor: pointer;
color: #CC0000;
height: auto;
display: inline-block;
border: 2px solid #CC0000;
border-radius: 4rem;
margin: 2px 0px 2px 0px;
padding: 8px 18px 8px 18px;
line-height: 1.2rem;
background-color: white;
font-family: -apple-system, "Segoe UI", "Helvetica Neue", sans-serif;
font-weight: bold;
text-decoration: none;
}
</style>Markdown:
[Required Reading Quiz due Jun 4th](https://canvas.sfu.ca/courses/44038/quizzes/168353 ':class=mybutton')As supported by standard Markdown, HTML snippets can also be included (and mixed) within Markdown , for example:
<div class="row">
<div class="column">
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
</div>
<div class="column">
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
</div>
</div>In additition to generating standalone Web pages and sites, you can embed Docsify-This web pages using iFrames in almost any platform. URL parameters can also be used to match each destination platform better visually.
Figure 3. Docsify-This iFrame (within the Canvas LMS Homepage), for example https://canvas.sfu.ca/courses/76289
<p><iframe style="overflow: hidden; border: 0px #ffffff none; margin-top: -26px; background: #ffffff;" src="https://docsify-this.net/?basePath=https://raw.githubusercontent.com/hibbitts-design/cmpt-363-222-pages/main&homepage=home.md&font-family=Lato%20Extended,Lato,Helvetica%20Neue,Helvetica,Arial,sans-serif&font-size=1&hide-credits=true" width="800px" height="950px" allowfullscreen="allowfullscreen"></iframe></p>As shown above, with the Canvas LMS a Canvas Page can be set as the course Homepage, and then an iFrame can be used for the content of that page. For more details, view How do I set a Front Page in a course? and Embed content in Canvas.
If a scroll bar is present, you may want to re-edit your iFrame code and adjust the "height" value.
The URL of a Markdown file rendered by Docsify-This can also be included inside of other systems as an external URL.
Many LMSs, including Canvas and Moodle, have the ability to include external URLs in their course navigation menus. For example, with the Canvas LMS you would use the Redirect Tool to display Docsify-This web pages.
Figure 4. Docsify-This External URL within Canvas LMS (used with the Redirect Tool), for example https://canvas.sfu.ca/courses/76289/external_tools/36154
url=https://docsify-this.net/?basePath=https://raw.githubusercontent.com/hibbitts-design/cmpt-363-222-pages/main&homepage=resources.md&edit-link=https://github.com/hibbitts-design/cmpt-363-222-pages/blob/main/resources.md&font-family=Lato%20Extended,Lato,Helvetica%20Neue,Helvetica,Arial,sans-serif&font-size=1&hide-credits=trueWith the Canvas LMS it is also possible to use an external web page as content within a course Module.
Figure 5. Docsify-This External URL with Page Table of Contents (used as a Canvas LMS Module), for example https://canvas.sfu.ca/courses/76289/modules/items/2816273
https://docsify-this.net?basePath=https://raw.githubusercontent.com/hibbitts-design/cmpt-363-222-pages/main&homepage=week-01.md&toc-narrow=true&font-family=Lato%20Extended,Lato,Helvetica%20Neue,Helvetica,Arial,sans-serif&font-size=1&hide-credits=trueThe following example Markdown templates are available which can be cloned/forked on GitHub or imported into Codeberg. Templates can also be downloaded and hosted just about anywhere online.
To use these templates you would generally do the following (specific instructions are included with each template):
-
Tap Use this template in the chosen template repository (upper-right green button) and then choose Create a new repository
-
Choose the name for your new repository to contain the files and then tap Create repository to copy the template files to your own GitHub account
-
View the home.md Markdown file in your newly created repository and copy it's URL
-
Go to https://docsify-this.net and paste the copied URL into the Markdown File URL field
-
Select the page options you want (e.g. Docsify Sidebar) and tap the View as Standalone Page button to view your Markdown file as a web page for sharing or embedding
Now that the template files are located on your own GitHub account, modify their content to fit your needs.
Figure 6. Docsify-This One Page Article Template, for example the Markdown file home.md and displayed by Docsify-This as https://docsify-this.net/?basePath=https://raw.githubusercontent.com/hibbitts-design/docsify-this-one-page-article/main&homepage=home.md&sidebar=true&maxLevel=3
Figure 7. Docsify-This One Page Course Template, for example the Markdown file home.md and displayed by Docsify-This as https://docsify-this.net/?basePath=https://raw.githubusercontent.com/hibbitts-design/docsify-this-one-page-course/main&homepage=home.md&toc=true
Figure 8. Docsify-This Multiple Page Site, for example the Markdown file home.md and displayed by Docsify-This as https://docsify-this.net/?basePath=https://raw.githubusercontent.com/hibbitts-design/docsify-this-multiple-page-site/main&homepage=home.md
Figure 9. Docsify-This Multiple Page Site, for example the Markdown file home.md, including the use of a custom Docsify a href="https://github.com/hibbitts-design/docsify-this-multiple-page-course-site/blob/main/_sidebar.md">Sidebar file, and displayed by Docsify-This as https://docsify-this.net/?basePath=https://raw.githubusercontent.com/hibbitts-design/docsify-this-multiple-page-course-site/main&homepage=home.md&sidebar=true&loadSidebar=_sidebar.md&loadNavbar=_navbar.md&hide-credits=true&browser-tab-title=CPT-363
Figure 10. Docsify-This LMS Content Pages Template, including such embeddable pages as a home page, weekly module, topics and more
There are multiple ways to get a raw Markdown file available online, here are three options to help you get started:
- Signup for a GitHub or Codeberg account
- Make a new repository, and create or upload your Markdown file
- View the Markdown file, and copy/paste that URL into the Docsify-This Markdown File URL field
- Signup for a GitHub account
- Create a gist with your Markdown file at https://gist.github.com
- Enter a filename ending with
.md(e.g.myfile.md) - Choose Create public gist and tap on that button
- Tap on Raw button in the upper right of your Gist field and copy/paste that URL into the Docsify-This Markdown File URL field
- Obtain login information for your Webserver
- Upload the Markdown file to your Webserver
- Navigate to the location of that file, view the contents in your Browser, and copy/paste that URL into the Docsify-This Markdown File URL field
Git is a free and open source distributed version control system, originally created by Linus Torvalds in 2005 for development of the Linux kernel.
Version control supports the management of changes, called revisions, to files... especially useful for pure text files such as those used by Docsify-This.
Figure 11. Local Version Control (source: https://git-scm.com)
As a distributed version control system, Git also support collaboration with multiple contributors.
Figure 12. Distributed Version Control (source: https://git-scm.com)
GitHub and Codeberg are examples of online Git services, providing point-and-click means to create and manage Git repositories.
In addition to supporting the hosting of Git repositories, online editing of repository content such as Markdown files (using the filename extension .md) is also provided.
- Locally Store Git/GitHub Repositories
- Push and Pull Repository Changes
Figure 14. GitHub Desktop Mac (source: https://git-scm.com)
To fully leverage the benefits of version control, and potentially collaboration using an optional "Edit this Page" link, store your Docsify-This Markdown pages within a GitHub or Codeberg repository and optionally use an app such as GitHub Desktop to push/pull changes to your desktop.
- Install GitHub Desktop (https://desktop.github.com)
- Enter your GitHub credentials as prompted
- Go to a GitHub repository web page, tap < > Code and then choose Open with GitHub Desktop OR go to a Codeberg repository web page, copy the HTTPS address, then in GitHub Desktop choose File > Clone Repository and paste the copied URL
- Choose the location for your cloned repository and tap the Clone button
Once your Docsify-This Markdown files are synced (i.e. cloned) to your desktop via GitHub Desktop you can then use the text editor of your choice, such as VSCode, Pulsar Beta (was Atom.io), Typora etc.
Using GitHub Desktop you can preview any changes and then commit those changes back to the repository. VSCode can also be used alone to both sync and editing files.
Figure 16. Docsify-This + Webserver Markdown Files
- Markdown Format
- Accessibility
- Creating and Editing Markdown on GitHub
- GitHub and Open Education Resources (OER)
- GitHub Desktop
- Markdown Desktop Editors