repository·develop·Indexed 12 days ago
https://github.com/docsifyjs/docsifyA lightweight documentation site generator that transforms Markdown files into a website dynamically in the browser without requiring a build step. Version 5.0.0 supports features like nested sidebars, custom key bindings, cover pages, and flexible CDN deployment via jsDelivr, cdnjs, and unpkg.
A Docsify plugin is a function that allows you to execute custom JavaScript code at specific stages of the Docsify lifecycle. It receives two arguments: hook (an object containing lifecycle methods) and vm (the Docsify instance).
function myPlugin(hook, vm) {
// ...
}index.html file which acts as the entry point for the application.onlyCover configuration option.Docsify follows a specific order when processing Vue content on every page load:
<script> tags: Any manual mounting logic in the file is run first.vueComponents: Global components defined in your config are registered.vueMounts: Specific DOM elements targeted by selectors are mounted.vueComponents found in the Markdown are automatically mounted.vueGlobalOptions.Key Behaviors:
<p> containing {{ foo }} or a <my-component />).Docsify automatically recognizes file extensions to determine how to embed them:
.html, .htm.markdown, .md.mp3.mp4, .oggYou can force a specific type using the :type attribute. For example, to embed a Markdown file as a code block, use :type=code.
[filename](_media/example.md ':include :type=code')After running docsify init ./docs, the following files are created in the ./docs directory:
index.html: The entry file for the application.README.md: The home page of your documentation..nojekyll: A file used to prevent GitHub Pages from ignoring files that begin with an underscore.You can update the home page by editing ./docs/README.md or add more pages to your site.
To have the sidebar update dynamically based on the current directory (e.g., showing sub-navigation when entering a folder), add a _sidebar.md file to each subdirectory. Docsify will load the _sidebar.md from the current directory level; if it doesn't exist, it falls back to the parent directory's sidebar.
You can use the alias configuration to control this fallback behavior and avoid unnecessary parent sidebar loading.
<script>
window.$docsify = {
loadSidebar: true,
alias: {
'/.*/_sidebar.md': '/_sidebar.md',
},
};
</script>To deploy to Netlify:
docs).docs/.HTML5 Router Support: If you are using the HTML5 router, create a _redirects file in your docs directory to ensure all requests are redirected to index.html with a 200 status code.
# Create _redirects in your docs directory
/* /index.html 200Upgrading from Docsify v4 to v5 primarily involves updating CDN URLs and theme files. Most configuration settings in window.$docsify and your Markdown content remain unchanged.
Key changes to apply:
/lib/ to /dist/.@4 to @5.core theme. Legacy themes like buble, dark, or pure are replaced by the core theme, though specific styles (like Vue) are now available as add-ons.If you were using non-version-locked URLs (e.g., //cdn.jsdelivr.net/npm/docsify/lib/...), you must update both the path and the version specifier.
You can define your navigation using a Markdown file by enabling the loadNavbar configuration option.
loadNavbar: true in your $docsify configuration object in index.html._navbar.md in your directory..nojekyll in your ./docs directory. This prevents GitHub from ignoring files that start with an underscore (like _navbar.md).Navbar Hierarchy: _navbar.md is loaded from the current directory level. If no _navbar.md is found in the current directory, docsify will fall back to the parent directory's _navbar.md.
<!-- index.html -->
<script>
window.$docsify = {
loadNavbar: true,
};
</script>
<script src="//cdn.jsdelivr.net/npm/docsify@5/dist/docsify.min.js"></script><!-- _navbar.md -->
- [En](/)
- [chinese](/zh-cn/)To add new pages, create markdown files within your docs directory. Docsify uses the filename to determine the route. For example, a file named guide.md will be accessible at /#/guide.
Route Mapping Examples:
docs/README.md => http://domain.comdocs/guide.md => http://domain.com/#/guidedocs/zh-cn/README.md => http://domain.com/#/zh-cn/docs/zh-cn/guide.md => http://domain.com/#/zh-cn/guideYou can also create a README.md file in a subdirectory to serve as the landing page for that specific route.
.
└── docs
├── README.md
├── guide.md
└── zh-cn
├── README.md
└── guide.mdDocsify allows you to extend Markdown link syntax with special attributes passed inside single quotes.
Use :disabled to make a link non-clickable.
By default, Docsify compiles relative links to internal routes (e.g., /demo/ becomes /#/demo/). To link to an actual file or external path without Docsify's routing interference, use :ignore.
You can also provide a title using the title keyword.
Use :target to specify where the link should open (e.g., _blank or _self).
[link](/demo ':disabled')
[link](/demo/ ':ignore')
[link](/demo/ ':ignore title')
[link](/demo ':target=_blank')
[link](/demo2 ':target=_self')