michaelcurrin/docsify-js-template

Starter template for a Markdown-based docs site 📒 🕸

DocsifyJS Template 📒 🕸

Starter template for a Markdown-based docs site

Preview

Instead of forking, rather make a new repo using this template button:

If you want to improve the original template, then fork it and make a PR.

Features

• 🏭 Template for a SPA modern docs site.
• 📗 Use your awesome project's existing markdown files.
• 🤩 Light on code – just add a single HTML file and optionally add cover page and navbar config.
• 🚀 Easy to host as a static site on GitHub Pages. No build step needed.

Purpose

How to use this project

• Create a new repo from the template and host it on GitHub Pages immediately. This is good for trying out Docsify or building a site project from scratch.
• Use this project as a base - follow instructions to download just the necessary files to your existing repo's docs directory
• View the live demo site to see what you'll get.

For more info on Docsify, see my DocsifyJS Tutorial. That covers intro to DocsifyJS, including installation, running and configuration. If you look at the repo, that has has more content and configuration than this relatively plain template site.

How to use Docsify in your projects

Copy files

Use one of the approaches below to setup Docsify in your own project.

A. Use this template

Create a new forked project based on this template by clicking the button below. You'll get a fork in your own repo.

You could start adding code outside of the docs directory, however this project is intended as a standalone docs site which can be configured for experimentation and used as reference.

B. Add Docsify to an existing project's docs directory

This will copy the contents of the docs directory from Github to the current folder - ideal if there is an existing project and you want to add to Docsify it.

1. Ensure you have curl command installed. Or use wget.
2. Navigate to your project's docs folder.

   cd my-project/docs

3. Download necessary files in the template docs directory to your project using this two-line command. (The -O flag will save the files locally, keeping the original filenames.)

   REPO_DOCS='https://raw.githubusercontent.com/MichaelCurrin/docsify-js-template/master/docs/'
   curl $REPO_DOCS\{_coverpage.md,_sidebar.md,.nojekyll,index.html,README.md\} -O

Customize

You can use your IDE to do find and replace across files.

Use the convenient replace.sh script in this repo to replace the template's values with your own.

1. Find the script.
   • If you used the template button, you've already got it.
   • If adding content to your existing project's docs, copy script to your project root (not docs directory)

     curl 'https://raw.githubusercontent.com/MichaelCurrin/docsify-js-template/master/replace.sh' -O
     chmod +x ./replace.sh

2. Modify the MY_ values then run this script to replace the template's value with your own.
3. Run the script from the project root against yours docs directory.

   ./replace.sh

4. The script can be deleted after you use it.

Now complete any remaining TODO items in the files.

Use template readme

If you clicked Use this template, followed the customize steps above, then the last thing to do is replace the project's README.md file with the template one.

mv README.template.md README.md

Then customize README.md as your own project.

Set up and run

Remote use

Whatever approach you use to set up a docs directory, you can use your own project or a forked template and serve your site on platform like GiHhub Pages or Netlify.

This template still works fine as a standalone online demo of Docsify that you can tweak. In a real project, you'd add your code at the repo root, outside of docs. Or you could move your docs site to the repo root on the gh-pages branch for GH Pages.

Serve locally

Follow this gist so you can view the docs site on a local webserver.

Go to my DocsifyJS Tutorial - Serve locally for more info on what DocsifyJS is and how to use it.

Related projects

A template using Docsify Themeable. It is a Docsify site but easier to use, it is prettier (in my opinion), and supports a theme system that is more advanced than that in Docsify.

• 

A template for Vue-based docs site. Except it uses VuePress to render a static site (better for SEO) rather than as a Single-Page Application like Docsify.

• 

A template for a Vue-based app.

• 

License

Released under MIT by @MichaelCurrin.

• You can modify and reuse this project.
• Please link back to the original repo somewhere in your project if you use this in any way.
• Including an original license copy.
  • If you add content from docs to your repo (or click Use this template) and then modify for your own needs so your copy is no longer a template, then you don't need to include a license.
  • If you do fork this repo then use it as your own template, then this project's license and copyright notice must be included with the software. source. Copy LICENSE to LICENSE-source and then update your copy of LICENSE with your own details.

docsify-js-template's Issues

Add more badges

Like stars and forks

See https://github.com/MichaelCurrin/repo-boilerplates

Find better emoji than one push pin

Add noscript

Create a spin-off of this using Docsify themeable

There's more control and maybe something of the things that bother me like the menu are fixed.

Don't use too much though otherwise it can be as heavy as a static site.

script does not work. have to rename files to all lowercase, without underscore and still has issues

replace script has a SED error code R and I can't figure out why.
nothing except the four lines are edited prior to running.

➜  docsify git:(master) ✗ ./replace.sh 
PATTERN
s/DocsifyJS Template/Flop Hub/g
s/MichaelCurrin\/docsify-js-template/flophub\/docsify/g
s/docsify/docsifyjs-template/g
s/Starter template for a markdown-based docs site/A two-sided hardware marketplace built on Kubernetes/g
sed: 1: "README.md": invalid command code R
➜  docsify git:(master) ✗ cd ..

Separate this project's instructions and general instructions

Mixing both in one README file feels messy.

Even create a separate _README template or snippet. Or move instructions to an original repo specific doc which can be deleted.

Or move instructions out to tutorial repo, though then its more coupled and less verbose.

Add wget instructions

Reduce color flash

When using a background like Unicron even fixed colors, the screen shows as green/red and then the custom color appears.

I am already using the custom color on cover as per docs. But set something in CSS to override the image behind that to be white/black/grey gradient as more neutral. Or even set that color there.

Use local CSS where possible to avoid fetching a file and then loading it. Or maybe the flicker is just JS execution.

Allow installation of docsify through NPM package file

This makes the project heavier, but means Docsify is not needed globally which is safer.

The index.html can still reference a CDN, to keep the flow simple (otherwise a build flow is needed to download and copy).

Rename to have quickstart in the name?

Or skeleton, template, etc. Be consistent across repos

And update links to this repo and site

Add doc menu

Add option to link to installation and usage docs and also create them.

Maybe create them with the command but safely don't overwrite them. They can be created with echo but having them in the repo is better.
Or just ensure curl uses a flag to not override existing files