How to Configure Docsify for Offline Documentation Viewing in ML-For-Beginners

Set offline: true in the Docsify configuration file and include the 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 – The entry point that loads Docsify and registers the offline plugin.
• docs/.docsify.js – The configuration object where the offline flag is enabled.
• docs/docsify-offline-plugin.js – The helper script that installs and activates the service worker.
• 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, which executes docsify-offline-plugin.js.
2. The plugin registers 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

Locate the configuration file at docs/.docsify.js and add the offline property to the global window.$docsify object:

// 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

Ensure the offline plugin script is loaded after the main Docsify library in docs/index.html:

<!-- docs/index.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>ML for Beginners Docs</title>
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
  <div id="app"></div>

  <!-- Docsify core library -->
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

  <!-- Offline plugin - must load after Docsify -->
  <script src="docsify-offline-plugin.js"></script>

  <!-- Configuration -->
  <script src=".docsify.js"></script>
</body>
</html>

The 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:

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 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:

# 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 and including docsify-offline-plugin.js in docs/index.html.
• Service Worker (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, 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 script in your index.html, set offline: true in your Docsify configuration object, and ensure the service worker file (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}