# How to Configure Docsify for Offline Documentation Viewing in ML-For-Beginners
> Learn how to configure Docsify for offline documentation viewing with the ML-For-Beginners guide. Enable caching with simple config changes.
- Repository: [Microsoft/ML-For-Beginners](https://github.com/microsoft/ML-For-Beginners)
- Tags: how-to-guide
- Published: 2026-02-28
---
**Set `offline: true` in the Docsify configuration file and include the [`docsify-offline-plugin.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/docsify-offline-plugin.js) script to enable service-worker-based caching for the ML-For-Beginners documentation.**
The **microsoft/ML-For-Beginners** repository uses Docsify to render its curriculum as a dynamic documentation site. Because Docsify fetches Markdown content on demand, learners typically need an active internet connection to access lessons. By configuring the offline plugin bundled with the repository, you can cache all course materials locally, enabling study in environments without network access.
## Understanding the Offline Architecture
Docsify’s offline capability relies on a service worker that intercepts network requests and serves cached assets when the browser is offline. The ML-For-Beginners repository provides the necessary scaffolding in the `docs/` directory.
### Core Components
The offline system consists of four key files:
- **[`docs/index.html`](https://github.com/microsoft/ML-For-Beginners/blob/main/docs/index.html)** – The entry point that loads Docsify and registers the offline plugin.
- **[`docs/.docsify.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/docs/.docsify.js)** – The configuration object where the `offline` flag is enabled.
- **[`docs/docsify-offline-plugin.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/docs/docsify-offline-plugin.js)** – The helper script that installs and activates the service worker.
- **[`docs/sw.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/docs/sw.js)** – The service-worker script containing the caching strategy (pre-generated by the plugin).
### How the Service Worker Caches Content
When a learner first visits the documentation site, the following sequence occurs:
1. The browser loads [`index.html`](https://github.com/microsoft/ML-For-Beginners/blob/main/index.html), which executes [`docsify-offline-plugin.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/docsify-offline-plugin.js).
2. The plugin registers [`sw.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/sw.js) as a service worker.
3. During the `install` event, the service worker pre-caches the core shell (HTML, CSS, JS) and creates a cache for Markdown content.
4. On subsequent navigation, the service worker intercepts fetch requests. If the network is unavailable, it returns the cached Markdown file, allowing Docsify to render the lesson without connectivity.
## Step-by-Step Configuration
To enable offline access for the ML-For-Beginners documentation, you must modify the configuration and ensure the plugin is loaded.
### Enable Offline Mode in [`.docsify.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/.docsify.js)
Locate the configuration file at [`docs/.docsify.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/docs/.docsify.js) and add the `offline` property to the global `window.$docsify` object:
```javascript
// docs/.docsify.js
window.$docsify = {
name: 'ML for Beginners',
repo: 'microsoft/ML-For-Beginners',
// Enable offline caching
offline: true,
loadSidebar: true,
subMaxLevel: 2,
// Additional Docsify options...
};
```
Setting `offline: true` signals Docsify to cooperate with the service worker and avoid fetching remote resources that are not cached.
### Register the Plugin in [`index.html`](https://github.com/microsoft/ML-For-Beginners/blob/main/index.html)
Ensure the offline plugin script is loaded after the main Docsify library in [`docs/index.html`](https://github.com/microsoft/ML-For-Beginners/blob/main/docs/index.html):
```html
ML for Beginners Docs
```
The [`docsify-offline-plugin.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/docsify-offline-plugin.js) file handles service worker registration automatically when the page loads.
### Verify the Service Worker Registration
After configuring the files, serve the documentation locally to verify that the service worker installs correctly:
```bash
npx serve docs
```
Open the site in a browser and navigate to several lessons. Then, open the browser’s Developer Tools (usually F12), go to the **Application** tab, and inspect the **Service Workers** section. You should see a registered worker for [`sw.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/sw.js) with a status of "activated and running."
To test offline functionality, disable your network connection and refresh the page. The documentation should render without errors, pulling content from the cache.
## Running the Documentation Locally
Because Docsify is a client-side renderer, no build process is required to view the ML-For-Beginners curriculum. Any static file server will suffice:
```bash
# Using npx (Node.js)
npx serve docs
# Using Python 3
python -m http.server 3000 --directory docs
# Using PHP
php -S localhost:3000 -t docs
```
Once the server is running, visit `http://localhost:3000`. Browse through the lessons to populate the service worker cache. After this initial visit, the entire curriculum remains available even if you disconnect from the internet.
## Summary
- **Docsify** renders the ML-For-Beginners curriculum dynamically in the browser, requiring a network connection by default.
- **Offline support** is enabled by setting `offline: true` in [`docs/.docsify.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/docs/.docsify.js) and including [`docsify-offline-plugin.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/docsify-offline-plugin.js) in [`docs/index.html`](https://github.com/microsoft/ML-For-Beginners/blob/main/docs/index.html).
- **Service Worker** ([`sw.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/sw.js)) pre-caches static assets and Markdown files, intercepting fetch requests to serve content when offline.
- **No build step** is required; serve the `docs/` folder with any static server and browse once to activate the cache.
## Frequently Asked Questions
### What is Docsify and why does it need offline configuration?
Docsify is a lightweight documentation site generator that parses Markdown files directly in the browser rather than pre-rendering HTML. Because it fetches content on demand via JavaScript, users typically need an active internet connection to view documentation. Configuring the offline plugin bundles these assets into the browser cache, enabling access in disconnected environments.
### How does the service worker cache documentation pages?
The service worker, registered by [`docsify-offline-plugin.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/docsify-offline-plugin.js), listens for the `install` event to pre-cache the site’s shell (HTML, CSS, and JavaScript). During browsing, it intercepts fetch requests for Markdown files and stores them in a runtime cache. When the network is unavailable, the worker serves these cached files instead of attempting remote requests, allowing Docsify to render content seamlessly.
### Can I use this offline setup for other Docsify sites?
Yes, the configuration pattern used in ML-For-Beginners is portable to any Docsify project. You need to include the [`docsify-offline-plugin.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/docsify-offline-plugin.js) script in your [`index.html`](https://github.com/microsoft/ML-For-Beginners/blob/main/index.html), set `offline: true` in your Docsify configuration object, and ensure the service worker file ([`sw.js`](https://github.com/microsoft/ML-For-Beginners/blob/main/sw.js)) is present in your document root. The plugin handles the rest of the caching logic automatically.
### Why does the first page load require internet access?
The initial visit must download the Docsify core library, the offline plugin, the service worker, and the first Markdown file to establish the cache. The service worker can only intercept and store assets after it has been installed and activated, which occurs during this first load. Once these files are cached, subsequent navigation—even to previously unvisited pages—can work offline as long as those specific pages were cached during an earlier online session.