Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/michaelcurrin/docsify-js-tutorial
Build a Markdown-based docs site using DocsifyJS and GH Pages 👩🏫 🏗 📒 🕸
https://github.com/michaelcurrin/docsify-js-tutorial
demo docs-generator docs-site docsify docsify-plugin docsifyjs docsifyjs-tutorial documentation github-pages markdown tutorial
Last synced: 2 months ago
JSON representation
Build a Markdown-based docs site using DocsifyJS and GH Pages 👩🏫 🏗 📒 🕸
- Host: GitHub
- URL: https://github.com/michaelcurrin/docsify-js-tutorial
- Owner: MichaelCurrin
- License: mit
- Created: 2019-08-28T20:14:19.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2022-06-14T19:20:24.000Z (over 2 years ago)
- Last Synced: 2024-05-19T19:22:43.733Z (7 months ago)
- Topics: demo, docs-generator, docs-site, docsify, docsify-plugin, docsifyjs, docsifyjs-tutorial, documentation, github-pages, markdown, tutorial
- Language: Makefile
- Homepage: https://michaelcurrin.github.io/docsify-js-tutorial/#/
- Size: 1.23 MB
- Stars: 34
- Watchers: 3
- Forks: 38
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# DocsifyJS Tutorial
> Build a Markdown-based docs site using _DocsifyJS_ and _GH Pages_ 👩🏫 🏗 📒 🕸
[](https://GitHub.com/MichaelCurrin/docsify-js-tutorial/tags/)
[](#license)
[](/CONTRIBUTING.md)
[](https://docsify.js.org/ "Go to Docsify website")
[](https://pages.github.com/ "Go to GitHub Pages docs")
## Preview
## Getting started
### Learn about Docsify
Follow the online tutorial. Start with the basics or get to the menu customization and styling in later sections. Code snippets and recommendations are provided, so you don't have to spend a lot of time on all the possible options and features covered in the docs that you don't need to know.
[](https://michaelcurrin.github.io/docsify-js-tutorial/)
### Use a template project
Want to make a Docsify site? I have a template project you can use. It has enough structure and sample content to get you going.
[](https://michaelcurrin.github.io/docsify-js-template/)
You don't need to fork it - unless you want to contribute changes.
## About the online tutorial 👩🏫
_This repo is one of my most starred and most forked repos - thanks for supporting._
The [Docsify](https://docsify.js.org/#/) site has a great guide for beginners. But with all the configs and plugin options available, the guide feels more like a dictionary than a recipe for setting up a custom docs site that is focused on content and not adding too much code or configuration. So I created this tutorial to take beginners and advanced users through setting up Docsify in ordered steps - noting as well when steps are optional or what choices there are.
This tutorial takes you from basic site setup and content to optional configuration of styling, menus and plugins. It aims to cover common use-cases in a logical sequence, rather than covering everything you could do. You can also jump to a later step if you want to use that as a reference.
It also assumes you already have a docs directory in a project and you want to turn it into a docs site. The tutorial gives you some tips and pitfalls to avoid, based on the author's experience.
This project's own site is built on _DocsifyJS_ so serves as a good example. It serves from the `docs` directory. There is no main application to separate from `docs` directory, so serving from that directory is just convenient.
See also the [Nested Example](/nested-example/README.md) section on the repo for understanding links in Markdown and the sidebar.
## Use a template 🖨️
If want to skip the tutorial and want a base project which has some sample data then go to the template repo linked at the top.
That is a template repo which was created to accompany this tutorial, so the layout and conventions will mostly be the same. The template only implements the basic steps from the tutorial.
Click _Use this template_ button and follow the instructions in the _README.md_ doc.
## Project aims 🎯
Some background on how I arrived at DocsifyJS as a docs site builder.
My aims for building a docs site were as follows and Docsify meets all of them:
- Add as little code and configuration as possible. Focus on the content, with a bit of styling.
- Be easy to maintain.
- Quick to get set up on existing projects.
- It should be easy to repeat across many projects, without having to deal to have headaches with each. (Like a lot of boilerplate code, or installation issues, or drift as layouts/features are added to one and not the others.)
- Have **no** HTML template/layout files to maintain.
- Reduce dependencies and keep installation simple.
- Light or no build step needed.
The docs site tool used here is [DocsifyJS](https://docsify.js.org/) which is a frontend JS library written in VueJS. But if you have never used before or never coded in JS before, you'll be guided through. The only JS you need to write in your config values. You also need to edit some HTML values and possibly write a YAML file for your navbar, which again is more configuration than code.
This project's tutorial covers the basics and provides minimal setup instructions. You can add the quickstart project to your **existing** docs folder. If you doc files are markdown files, you don't have to rename them and their formatting can mostly stay the same i.e. no frontmatter or special syntax and the pages still render well as plain markdown even. But some links may need updating since `/docs` folder is now the root of the app.
Unlike static site builders like Jekyll or Hugo, you do **not** need to install or run a site generator or change the formatting or metadata of your markdown files. Your also don't need any separate config file - the configuration is handled in the _index.html_ page, which is also where dependencies are fetched in the browser and where the app starts.
_Docsify_ works as a single-page application on this one page - data from your markdown files is pulled in and displayed within the _Docsify_ UI shell. There are no template layout files to manage and you can choose from some themes easily without things breaking like when you switch themes in other static site generators.
## Contributing
See [Contributing](/CONTRIBUTING.md) guidelines.
## License
Released under [MIT](/LICENSE) by [@MichaelCurrin](https://github.com/MichaelCurrin).
- You can modify and reuse this project.
- A copy of the license and copyright notice must be included with the software, according to this [MIT definition](https://choosealicense.com/licenses/#mit).
- Please link back to this repo somewhere in your project.