Markdown Publishing with Docsify⁠–⁠This

A detailed guide to Markdown publishing using the open source Docsify-This.net project.

Markdown

What is Markdown?

Markdown is a markup language used to format the display of content stored as plain text - similar but simpler than HTML formatting

Why use Markdown?

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

Markdown Examples

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

![Image Alt Text](imagefile.jpg)  

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.

Hosting Markdown Files

There are multiple ways to get a raw Markdown file available online, here are three options to help you get started:

GitHub or Codeberg

Step 1: Create a New Repository

Log in or Sign up to GitHub or Codeberg
Create a new repository:
- Tap the + icon and select New Repository
- Fill in the repository details:
  - Choose a Repository Name for your repository (e.g., docsify-this-demo)
  - Confirm that the Visibility is Public
- Tap Create Repository

Step 2: Add Your Markdown Content

Option A: Create a New Markdown File

Go to your new repository, tap Add File and then choose New File
Name your file and use the .md extension (e.g., demo.md)

Enter your Markdown content. For example:

# Welcome!

This is my sample Markdown file.

Option B: Upload an Existing File

Go to your new repository, tap Add File and then choose Upload File
Choose your file and make sure it uses the .md extension (e.g., demo.md)

Step 3: Commit the Changes

Commit your file:
- Provide a Commit Message (e.g., "Create demo.md")
- Tap the Commit Changes button

Step 4: Verify the File and View it with Docsify-This

In your repository, view the file to see the rendered Markdown
Copy the file URL from your Browser's address bar
Go to Docsify-This.net and paste the copied URL into the Markdown File URL field
Tap the Publish as a Web Page button to view your Markdown file rendered as a web page using Docsify-This

Gist (GitHub Gists)

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

Personal or Organizational Website

Obtain login information for your Webserver
Upload the Markdown file to your Webserver with a filename ending with .md (e.g. myfile.md)
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

Publishing with Markdown

Markdown Converters
- For example, Pandoc
Markdown Static Site Builders
- For example, Jekyll
Markdown Dynamic Renderers
- For example, Docsify

Docsify-This

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.

Getting Started with Docsify-This

To use the Docsify-This Web Page Builder enter the URL for an online Markdown file and tap the 'Publish as a Web Page' button. The Markdown file will then be rendered as a web page with it's own URL that can then be copied and shared.

Figure 1. Docsify-This Web Page Builder

Example Docsify-This URL Created by 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.

Basic Customization

The 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 Docsify-This URL generated includes these same URL parameters.

Editing a Docsify-This URL

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

Example Docsify-This Usage Scenarios

Publish your Markdown files as web pages, with no website setup or build process required
Visually style your web pages using a point-and-click Web Page Builder
Share existing GitHub-hosted Markdown files as 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

Markdown CSS Classes

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

![UX - User Experience](https://raw.githubusercontent.com/hibbitts-design/publishing-with-docsify-this/main/images/12650723674_d5c85af332_k.jpg ':class=banner-image')

Custom Markdown CSS Classes

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:

Custom CSS Class Button

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

HTML Snippets

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>

Ready-to-Use Templates

The 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 a Web 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.

Docsify-This LMS Content Pages Template

Figure 8. Docsify-This LMS Content Pages Template, including such embeddable pages as a home page, weekly module, topics and more

For detailed examples and customization options, visit the complete Docsify-This documentation.

Embedding Docsify-This Pages

iFrames

In additition to generating 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 9. 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.

External URL

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 10. 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=true

With the Canvas LMS it is also possible to use an external web page as content within a course Module.

Figure 11. 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=true

Leveraging Git with GitHub or Codeberg

Git

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

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 12. Local Version Control (source: https://git-scm.com)

Collaboration

As a distributed version control system, Git also support collaboration with multiple contributors.

Figure 13. Distributed Version Control (source: https://git-scm.com)

GitHub and Codeberg

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.

Figure 14. GitHub Markdown File

Docsify-This + GitHub or Codeberg Markdown Files

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.

Setting up GitHub 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

GitHub Desktop

Locally Store Git/GitHub/Codeberg Repositories
Push and Pull Repository Changes

Figure 15. GitHub Desktop Mac (source: https://git-scm.com)

Desktop Text Editors

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 + GitHub Markdown Files Workflow

Figure 17. Docsify-This + Webserver Markdown Files

Additional Resources

Markdown Format
Accessibility
- Improving The Accessibility Of Your Markdown
Creating and Editing Markdown on GitHub
- Quickstart for writing on GitHub
- Authoring With Markdown
GitHub and Open Education Resources (OER)
- Create and publish OER with GitHub
- OER on GitHub What, Why, & How
GitHub Desktop
Markdown Desktop Editors

Name		Name	Last commit message	Last commit date
Latest commit History 253 Commits
images		images
.gitignore		.gitignore
README.md		README.md
_coverpage.md		_coverpage.md

hibbitts-design/publishing-with-docsify-this

Folders and files

Latest commit

History

Repository files navigation