The docsify website recommended in this issue can instantly generate your documents. Unlike GitBook, it does not generate static HTML files. On the contrary, it will cleverly load and parse your Markdown files and display them as websites.
characteristic
- HTML files without static construction
- Simple and lightweight
- Intelligent full-text search plugin
- Multiple themes
- Useful plugin API
- Emoji support
- Compatible with IE11
- Support server-side rendering
Quick start
Suggest installing docsify cli globally to help initialize and preview websites locally.
Npm i docsify-cli-g in the subdirectories init
i docsify-cli -g In the subdirectories' init 'initialization
If you want to/ Write documents in the ‘docs’ directory using the’ init ‘command.
docsify init ./docsWriting Content
After completion, you can see the file list in the subdirectories’ init ‘/ docs
- Index.html as the entry file
- README.md as the homepage
- . nojekyll prevents GitHub Pages from ignoring files starting with an underline
You can easily update the content in the document/ docs/README.md， Of course, you can also add more pages.
Preview your website
Use the local server docsify serve to run. You can preview your website on the browser http://localhost:3000 .
docsify serve docsManual initialization
If you don’t like npm or can’t install the tool, you can manually create index.html:
<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta charset="UTF-8">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/themes/vue.css" />
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
//...
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
</body>
</html>Specify docsify version
Please note that in the following two examples, when a new major version of docsify is released (e.g.=>v5. x.x), the docsify URL needs to be manually updated. Regularly check the docsify website to see if new major versions have been released.
Specify the major version @ 4 in the URL () to allow your site to automatically receive non-destructive enhancements (i.e. “minor” updates) and bug fixes (i.e. “patch” updates). This is the recommended way to load docsify resources.
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/themes/vue.css" />
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>If you want to lock docsify to a specific version, please @ specify the full version after the symbol in the URL. This is the safest way to ensure that your website looks and behaves the same, regardless of any changes made to future versions of docsify.
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4.11.4/themes/vue.css">
<script src="//cdn.jsdelivr.net/npm/docsify@4.11.4"></script>Manually preview your website
If Python is installed on your system, you can easily use it to run static servers to preview your site.
cd docs && python -m SimpleHTTPServer 3000cd docs && python -m http.server 3000Load dialog box
If you wish, you can display a loading dialog box before docsify starts rendering your document:
<!-- index.html -->
<div id="app">Please wait...</div>If you change, you should set the data app attribute el:
<!-- index.html -->
<div data-app id="main">Please wait...</div>
<script>
window.$docsify = {
el: '#main'
}
</script>configuration
Window. $docsify You can configure Docsify by defining it as an object:
<script>
window.$docsify = {
repo: 'docsifyjs/docsify',
maxLevel: 3,
coverpage: true,
};
</script>Configuration can also be defined as a function, in which case the first parameter is the Docsifyvm instance. This function should return a configuration object. VM is very useful for referencing in places such as discounted configurations:
<script>
window.$docsify = function(vm) {
return {
markdown: {
renderer: {
code(code, lang) {
// ... use `vm` ...
},
},
},
};
};
</script>Load navigation bar
- Type:Boolean|String
- Default:false
_If navbar.md is true, load the navigation bar from the Markdown file; otherwise, load it from the specified path.
window.$docsify = {
// load from _navbar.md
loadNavbar: true,
// load from nav.md
loadNavbar: 'nav.md',
};Load sidebar
- Type:Boolean|String
- Default:false
_If sidebar.md is true, load the sidebar from the Markdown file; otherwise, load it from the specified path.
window.$docsify = {
// load from _sidebar.md
loadSidebar: true,
// load from summary.md
loadSidebar: 'summary.md',
};Hide sidebar
- Type:Boolean
- Default:true
This option will completely hide your sidebar and will not display any content on the side.
window.$docsify = {
hideSidebar: true,
};homepage
- Type:String
- Default:README.md
README.md will be considered as the homepage of your website in your docs folder, but sometimes you may need to provide another file as your homepage.
window.$docsify = {
// Change to /home.md
homepage: 'home.md',
// Or use the readme in your repo
homepage:
'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md',
};If you have a link to the homepage in the sidebar and want it to be displayed as active when accessing the root URL, make sure to update the sidebar accordingly:
- Sidebar
- [Home](/)
- [Another page](another.md)theme
There are some available themes, including official and community made ones. Copy custom themes from Vue and buble websites, as well as black style themes contributed by @ liril net.
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css" />Compressed files can be found in/lib/themes/
<!-- compressed -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/buble.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/dark.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/pure.css" />If you have any ideas or want to develop a new theme, please feel free to submit a pull request.
GitHub page
There are three places to fill documents for your GitHub repository:
- Docs/Folder
- MAIN Branch
- Gh pages branch
We suggest that you save the file to the repository branch/ In the docs folder. Master, then select the master branch/docs folder as the GitHub Pages source in the repository settings page。
GitLab page
If you want to deploy the master branch, please use the following script to create a. gitlab-ci.yml:
The solution for. public is that cp will not copy to public/itself in an infinite loop.
pages:
stage: deploy
script:
- mkdir .public
- cp -r * .public
- mv .public public
artifacts:
paths:
- public
only:
- master—END—
Open source protocol:MIT license
