## Welcome to Kiwix JS for Windows

#### Version 2.0 (changes)

### Please read this important information

DISCLAIMER: Please be aware that Kiwix works with offline archives. To get updated info, you will need to download a new archive periodically. Information in official archives is free, open source and provided by volunteers. Kiwix gives no guarantee as to the accuracy of information in the archives you access with this app.

IMPORTANT: To use this app, you must download an offline ZIM archive and store it on your device! You can do this from the Configuration page , or else see the About page for more information.

Kiwix JS is free and open source. If you like it, please leave a positive review. Constructive feedback and help with improving the app are very welcome: see About section.

### Changes in version 3.x

- Support native auto dark/light theming system in new Wikimedia ZIMs (SW mode only)
- New keyboard shortcuts for article search: /, Ctrl-K and Home
- Faster, more reliable ZIM download library, now using the Kiwix catalogue service (OPDS)
- Fixed display of ISO language codes in library languages dropdown
- Modernized the app's user interface framework, making it lighter and faster
- Removed dependency on jQuery completely
- Improved security of the Electron app's local server, with new controls for access over your local network
- Fixed broken printing of articles
- Added guides for installing the PWA in major browsers on GitHub site
- Fixed blank page when opening an article in a new tab or following a link to a section
- Fixed display of grid-style (masonry) landing pages
- Prevent popovers on Wikivoyage custom landing page
- Various dark-mode display fixes
- Fixed touch gestures for sliding away the top and bottom bars
- App now responds faster when you are offline, instead of waiting for network timeouts
- Fix incorrect auto-update of custom apps to the base app
- Added Docker Compose configuration for easier local deployment
- New developer mode (Expert Settings) to facilitate debugging and development of the app
- Updated Electron and NWJS frameworks, plus many security updates to dependencies

And there's more...

### Features in Version 3.x

▼

- Support for all known ZIM types from Wikipedia 0.5 to Zimit v2
- Huge range of supported browsers and frameworks
- Full-text searching of ZIM contents using javascript-libzim
- Cutting-edge Origin Private File System support with best-available fallbacks
- Built-in DarkReader support for nearly all ZIM types
- Display article previews in popovers for Wikimedia archives
- Use multiple ZIM archives simultaneously with File Handling API
- ZIM content is loaded in a secure sandbox for your protection
- Download ZIM archives in-app and display download progress
- Read Zimit archives you create yourself with youzim.it
- Open a new browsable tab or window
- In-page searching and highlighting
- Title and URL search with wildcards .* or regexes
- Alphabetical index of all articles in archive (type space in search field)
- Find assets by URL in ZIM archive by prefixing namespace (or type space + / in search)
- Printing articles (with optional filtering for Wikipedia articles)
- Transform Wikipedia layout from mobile to desktop style and vice versa
- Download and save content from ZIM
- Support full-screen and orientation lock in most browsers and frameworks

##### Modal title goes here

Modal text goes here

##### Please choose print options

Resize document for printing:
Current value: 75%
Print images (default: yes)

Options below ONLY apply to Wikimedia ZIMs

Print the desktop (not mobile) style (default: yes) Print navigation boxes (default: no) Print endnotes (default: no) Print External Links / Further Reading (default: no) Print See Also (default: no) Print infoboxes (default: yes)

## Kiwix JS Windows

### Offline Wikipedia Viewer (Version )

Packaged ZIM archive:

- Adding archives and languages
- Changelog and Features
- Security
- Themes (dark and light)
- Style transformations (desktop, mobile) and collapsible sections
- File handling and File System access
- Title search syntax and alphabetical ZIM Archive Index
- Full-text search
- Removing navigation bars
- Link handling, dynamic content and image download
- Window and tab management
- Browser support
- Express server (Electron app)
- Technical Information
- Privacy Policy
- Feedback and Support
- Credits and Licence
- Official site : https://www.kiwix.org/

DISCLAIMER: Please be aware that Kiwix works with offline archives. To get updated info, you will need to download a new archive periodically. Information in official archives is free, open source and provided by volunteers.
Kiwix gives no guarantee as to the accuracy of information in the archives you access with this app.

Kiwix aspires to make the world's knowledge available to everyone for free. If your Internet access is expensive, slow, unreliable, insecure or censored, you can still gain access to a huge repository of knowledge and culture in almost every language using Kiwix offline archives.

To use this app, you will need to obtain/download one or more archives (called ZIM archives). You can download them in this app (see Usage below), or if you know someone with an archive you want, you can also share archives, e.g. on a USB stick. Archives are available in many different languages for resources such as Wikipedia, WikiMed, Wiktionary, Wikivoyage, Project Gutenberg, TED Talks, Stackexchange, etc. You can access this virtual offline encyclopaedia even if you are undertaking a long plane journey, hiking, and travelling or living in areas with weak or non-existent Internet access.

Offline archives use the OpenZIM format. This app is regularly tested with a range of different archives, and works with almost all of them, depending on the capabilities of your browser or framework. There is now full support for Zimit archives, including support for Zimit v2. For more information on Zimit and how to make your own ZIM archives, see youzim.it.

You can search through the titles of articles in each archive to find the one you want, or view all the article titles with the ZIM Archive Index (see Title search). There is support for full-text search in the PWA and Electron apps (for ZIM archives that include a full-text index).

On some Wikipedia and Wikivoyage pages you will see map pins: . This will open a map centered on the pin location in online Open Street Maps (if you have an Internet connection). The Windows 11 offline Maps app has unfortunately been deprecated, so this is the only way to view maps in the app currently.

### Usage

#### Step 1: Download some content

You can browse the Kiwix repository on the Configuration page, and the app will provide instructions according to the type of file you download. Alternatively, visit https://download.kiwix.org/zim/ or https://library.kiwix.org using a regular computer. To use all the features of ZIM archives that have dynamic content (e.g. PhET), the needs to be running in PWA/ServiceWorker mode (see Performance/compatibility settings in configuration), which is available in modern browsers (on iOS devices it is only available in Safari).

#### Step 2: Copy the content onto your device

If you have enough space, you can put several archives on your device storage. If you download the content directly in the app, ensure you save the file to the device and note the location of the file once the download has completed. For PC users: if you see that the ZIM archive has a Kiwix icon, you may be able to open it by double-clicking it. For Mobile users: if you downloaded via a PC, you will generally need to use a USB cable to copy the ZIM archive(s) to an accessible location on your device, such as the SD card or the main storage area if there is enough space there.

#### Step 3: Go to the "Configure" menu and select your ZIM file (or double-click / drag-and-drop your file into the app)

On the Configuration page, tap the "Select storage" button. If you have downloaded more than one archive, or you have a split ZIM archive consisting of several 2GB files, then you will need to pick the folder that contains these files or else (in older browsers) you will need to select all the split parts. If you have just one unsplit ZIM archive, you can instead pick the file directly, using the respective buttons on the Configuration page (you may need to tap "Select Storage" first). In most modern contexts the archive will be remembered on next launch (Firefox, Safari and IE11 are exceptions). If in the future you add more files to a folder you have selected, then you can use the rescan button to refresh the list of archives in the folder.

Alternatively, in the UWP app, and experimentally in an installed PWA on the PC, you can simply double-click the ZIM file to launch it in the app, even if the app is closed (your choice will be remembered on next launch). You can also drag-and-drop your ZIM file into the app, but it may not be remembered on next launch in all contexts (try it if this method interests you!).

#### Step 4: Enjoy your content offline!

### Changes in 1.0

### Privacy policy

When installed, Kiwix JS Windows works offline, and does not collect or record any of your personal data. It only remembers your browsing history for the duration of a session (for the purpose of returning to previously viewed pages). This history is lost on exiting the app with the optional exception of the last-visited page.

If you access this app from a secure web server (e.g. the PWA server), it will only work offline if your browser is capable of installing a Service Worker (note that on iOS devices, ServiceWorker mode only works in Safari). If you install, bookmark or add the PWA version to your home screen, then it will work offline (if ServiceWorker Mode is available), but note that by design any PWA will periodically check the PWA server (in this case, https://pwa.kiwix.org/), if it is available, to check for an updated Service Worker.

Electron and NWJS versions of the app may access GitHub on each start of the app to check for an update. The installer (setup) version for Windows, and the AppImage version for Linux, will also self-update. You can block the update check in these apps by unchecking the Allow Internet Access checkbox.

By default, this application will remember your last-visited page for each ZIM between sessions using local storage or a cookie that is accessible only by this app on this device. If you are accessing sensitive information that you do not wish to be displayed next time you open this app, we recommend that you turn this option off in the Configuration options.

This application only reads the archive files that you explicitly select on your device and files included in its own package: it is not capable of reading any other files. It will only access the Kiwix download server if you specifically request it to access the download library for ZIM archives on the Configuration page. If you run the app as a PWA, it will cache its own code from the secure PWA server and then can be used offline. Some ZIM archives contain active content (scripts) which may, in rare circumstances, attempt to contact external servers for incidental files such as fonts. These scripts will only run if you enable Service Worker mode in Configuration.

If you believe your Internet access is insecure, or is being controlled or censored, we recommend that you completely shut down your Internet access (Data or WiFi) before using the application.

Additionally, if you obtained this app from a Vendor Store (including extensions), then the Store operator may track your usage of the app (e.g. download, install, uninstall, date and number of sessions) for the purpose of providing anonymous, aggregate usage statistics to developers. If this concerns you, you should check the relevant Store Privacy Policy for further information.

Builds of this app are available that do not use a Store or an online Service Worker. Please see:

- Releases
- NWJS version - this version is completely standalone and will never self-update.

### Security of your ZIM archives and your browser

Most ZIM archives nowadays contain active content (scripts). Although we sandbox content in the ZIM as much as possible and use a strict Content Security Policy, we have to interact with the loaded content, and so we cannot fully lock it down. When the app is running in its default mode (in modern browsers), it is possible that a deliberately malicious ZIM from an untrusted source could break out of the sandbox and do nasty things like redirecting your browser to third-party or phishing sites. To mitigate against this, the app asks you to indicate that you trust the source of a ZIM when you first open it, and offers to open the ZIM in Restricted mode first, so you can check the validity of the content. Restricted mode prevents most dynamic content from running. When you next open a trusted file, the app will automatically switch back to ServiceWorker mode. If you make a mistake, and accidentally trust a malicious ZIM, then you should reset the app using the button in Configuration (and, of course, delete the ZIM).

### Themes (dark and light)

The default theme for the app is light. There are three dark themes available:

- Standard - This is best for Wikimedia archives and provides a carefully designed dark theme that works well with Wikipedia, WikiMed, and other Wikimedia content
- Invert - A generic inversion theme that re-inverts images to display them correctly
- DarkReader - Uses a built-in DarkReader script, which works best for Zimit archives

To toggle between basic light and dark modes, use the button in the top toolbar. For more fine-grained control over themes, including selecting specific dark themes, use the options in the Configuration page under "Display settings".

### Style transformations (desktop, mobile) and collapsible sections

The options in configuration to transform Wikimedia ZIMs from desktop to mobile style and vice versa attempt to mimic standard desktop and mobile styles for Wikimedia content. Please note that the latest ZIMs (ActionParse ZIMs with the Vector skin) are in desktop style by default, and in this style sections such as headers in articles are not collapsible. If you wish to have collapsible headers, please select the option "Use Wikimedia mobile style" in Configuration (under Display style). You may also set the option to collapse all sections by default, which is useful for browsing large articles on narrow screens.

### File handling and File System access

This app reads very large files stored on your device. All versions of the app can pick a file from any user-accessible location, and on desktop browsers, you can drag-and-drop any ZIM archive into the app. Some versions of the app can also be granted access to a folder or directory in which you may store several ZIM archives. If this option is available, you will see a "Select folder" button (after clicking "Select storage"). In almost all cases, except for installed Electron apps, recent Chromium desktop browsers, or if you are using the Origin Private File System (see below), you will be asked to grant permission to access previously picked files or folders every time the app launches (usually this is just one or two clicks). This is a security feature of your browser and operating system.

Chromium desktop browsers support Persistent Permissions and the File Handling API when you install the PWA. Persistent Permissions are available in Chrome, Edge, and other Chromium browsers as of version 122: the second or third time you open a file or folder, you will be asked if you wish to grant persistent permission. The File Handling API allows you to associate ZIM files with the app, so that when you double-click a ZIM file in your system's file explorer, it will open in the app. The first time you do this, you will be asked for permission to handle ZIM archives, and the browser will remember your choice. You can change your choice in the browser settings. Each time you launch a ZIM, it will open in a separate instance of the app, allowing you to browse multiple ZIMs at the same time. Note that multiple instances are not currently supported in the Electron/UWP apps.

#### Origin Private File System

In some modern browsers, you will see the option "Use Private File System" under the File and Folder selectors. On Android, this is the default storage mode (as it is much, much faster). If you select this option, then the app will request an Origin Private File System (OPFS) from the browser. Then, when you pick a ZIM file, instead of opening it, it will be stored in the OPFS. You may also select more than one archive to store in the OPFS, including all the parts of a split ZIM file (`.zimaa`, `.zimab`, etc.). Note that in this case, only the `.zimaa` entry will be displayed in the file list. If you drag-and-drop a file into the app while the OPFS is displayed, that file will be not be stored in the OPFS, but instead will be opened and displayed.

You may also download archives directly into the OPFS by using the appropriate download link in the Dowmload Library. Look for the link under "Direct download to Origin Private File System". Downloading this way is suitable for archives of up to around 2GB in size, depending on your download speed. Larger files may take too long, and it is generally better to use a browser-managed download link for very large files. Then, if you wish, you can move the file into the OPFS using the "Add file(s)" picker.

If you want to delete an archive from the Private File System, click the icon, and then click on the file you wish to delete. You will be asked for confirmation.

In some cases, you may be able to export an archive from the OPFS to the visible file system. Click the icon, and then click on the file you wish to export. The OPFS copy of the file is not deleted after export. If you do not see the export icon, then this feature is not available in your browser.

On iOS in Safari, the OPFS appears to be supported, but there is currently no way to download or move a file from the user-visible file system into the OPFS. This is because the `WriteableFileStream` API is not yet available on iOS, but it may become available soon.

The main advantages of the OPFS, especially on mobile, are:

- that the file system can be accessed by the app without needing to give permission, even after you relaunch the app (the last selected archive will automatically launch);
- Additionally, once a file is stored in the OPFS, access to it, e.g. on Android, is much faster than with standard file picking.

However, there are some limitations of the OPFS:

- the file system has a quota set by the browser, which may be very small in some browsers;
- on mobile OS, it can take a long time to store a file in the OPFS, especially if it is larger than 1GB. On Firefox for Android, importing a file is very slow -- it can be faster to download the file directly into the OPFS from the Download library;
- when you clear the app's data (e.g. clearing cookies, etc.), the browser can delete the file system and any files in it without warning;
- any file you store here will only be accessible by this app (unless you export it to the visible file system).

### Title search syntax and alphabetical ZIM Archive Index

All versions of this app support basic title search, which is very fast and matches the start of an article title. Some versions may also support full-text searching (see below).

You can quickly access the search bar using keyboard shortcuts: press the Home key, the / key (forward slash), Ctrl+K (or Cmd+K on Mac) to focus the search field from anywhere in the app. In PWA or Electron contexts, you can also use the traditional browser address bar shortcuts Ctrl+L (or Cmd+L) and Alt+D.

With title search, if you search for 'France' you will get 'France (country)', 'France (disambiguation)', 'France (film)', etc. This kind of search tries to be case-insensitive, but the number of case variants tried is necessarily limited.

You can also use the wildcards `.*` or `.+` as part of your title search (these follow regular expression syntax: if you don't know the difference then use `.*`). For example, you can search for 'list.*medieval', and you will get (in full English Wikipedia) 'List of Medieval bestiaries', 'List of Medieval topics', etc.

Incorrect search syntax! If you get this message, it's because you used a wildcard but the syntax was incorrect. Everything after the wildcard must be a valid regular expression or else the search will fail! For simple text or numbers after a wildcard, don't worry, it'll work fine, but you need to be aware that regular expressions reserve characters like '?', '(', '^', '$', '*', '+', so these (and others) must be used correctly if you use wildcards with them. You might be able to correct an error by placing a backslash before each reserved character, e.g. `list.*\(france`.

Wildcards can come anywhere in a string, including at the beginning. This works fine for Stackexchange, Gutenberg, PhET and similar ZIMs, and if full-text search is not available, using a wildcard is the only way to get all the Stackexchange questions on topics/words that don't have a tag. For Wikipedia, wildcards work best when they come after a simple string. If your search text starts with a wildcard in full English Wikipedia, it will start searching at the very beginning of the index and try to search through everything (there are millions of titles)! It will give up after somewhere between 250,000 and 1,000,000 searches (this is 10,000 x the value you set in Configuration for max search results).

You can now search for assets like images or other non-HTML files in a ZIM by prefixing a namespace. For example, in older ZIMs, all images are in namesapce `I`, so you would type, e.g., `I/aquarius`. In newer ZIMs, all contents (including assets) are in namespace `C`, so to distinguish images, you might need to add a file extesnions, like `C/aquarius.*webp`.

You can see the full alphabetical ZIM Archive Index by typing a space in the title search box. This is useful for ZIMs that have descriptive titles where you don't know the exact title you are searching for (e.g. Gutenberg or TED Talks, especially in Restricted mode, or for browsing Stackexchange or PhET). You can change your alphabet in Configuration for non-Roman alphabets. You can also show the full URL index by typing space / (a space followed by forward slash).

If not enough results are returned in your searches, you can increase the maximum number of search results using the slider in Configuration (under 'Navigation, search and other').

For the geeks, you can also use full regular expressions enclosed in non-capturing parentheses, like `(?:My\sCrazy\sSearch(es)?$)`. Alternatively, you can use full regex syntax after a wildcard (not before, except that '\s' will be converted to a space). Regex syntax will match titles in a case-insensitive manner. You can search for different diacritics with a regex like 'discours.*m[eé]thode' or `Gonz.*[áa]lez I[nñ][áa]rrit[uùú]`. Long searches will give up after maxSearchResultsSize * 10^4 title scans.

### Full-text search

Some versions of this app (PWA and Electron-based) support full-text search if your ZIM has a full-text index, as well as the display of snippets for items in the full-text index. The API panel in Configuration will tell you whether the loaded ZIM and app support full-text search. A full-text search will be launched automatically after the title search if the latter didn't return the maximum number of results you have set in Configuration (default is 20 on desktop, lower on mobile). Users of iOS will need to be on iOS 15+ for full-text search to work (if you are on an earlier version, we recommend you disable use of libzim WASM/ASM in Expert settings -> Troubleshooting and development).

Full-text results and snippets are displayed after any matching title search results. Full-text search results can be considerably slower than title search with very large ZIM archives. If you see the search result you want, you can click on it without having to wait for the full-text results. You can navigate the search results with your keyboard as well as by tapping or clicking on them. Snippets will open automatically if you hover over their summary entry, or you can tap the snippet header to open and close.

If you are using the PWA on Android, please note that search with snippets is only enabled by default for archives in the Origin Private File System. This is because conventional file access on most Android versions is far too slow, but it is much faster in the OPFS. You can override default settings in Configuration.

### Removing navigation bars

The default setting is for the top and bottom navigation bars to slide away when you scroll down and slide back when you scroll up. However, in some ZIM archives, e.g. PhET, it is not possible to scroll, and the navigation bars can obscure some content. In this case, in most browsers you can swipe decisively up or down on the window (with touch or with the mouse wheel/touchpad) to toggle the display of the navigation bars. In all browsers, you can also use the `Ctrl/Cmd` + `UpArrow`/`DownArrow` keys.

### Link handling, dynamic content and image download

This app does its best to handle links to special ZIM content, like active (dynamic) content, embedded videos, downladable content (EPUBs, PDFs) and images, but not everything works smoothly with every option.

The app can usually operate in two modes: "Restricted" (which manipulates the content of the article) and "ServiceWorker" (which tries to get out of the way and let the ZIM do its thing - see below under Technical information for a fuller explanation). Restricted mode doesn't support active or dynamic content. You will usually get an Active Content Warning popping up at the top of the landing page (Home) if you open a ZIM that requires you to switch to ServiceWorker mode. If you can't switch, you can often still access content in these archives by using title search or typing a space in title search to show the ZIM Archive Index (see above), but some things, especially any proprietary User Interface, won't work.

You can download images (as long as they haven't been inserted dynamically) by turning on the option Allow image manipulation in Configuration. Then you will be able to right-click an image and save it to disk or open it in a new tab (only tested in Wikimedia ZIMs). However, this doesn't work in the UWP or NWJS apps. Workaround for the UWP app: you can enable the Download or open current article (breakout link) option, export the article to a new browser tab (by clicking the Breakout icon), and then you will be able to manipulate images in the browser tab. Please note that enabling Image manipulation or the Download/ feature can interfere badly with some ZIMs that rely heavily on active content. So turn these options off if you are using such ZIMs.

You can download EPUBs and PDFs, e.g. from Gutenberg ZIMs, in Restricted mode, but the proprietary User Interface doesn't work (use title search instead). In the UWP Desktop app in ServiceWorker mode, you need to enable the option Open ZIM links in new tab (or window) in Configuration to be able to download EPUBs and PDFs. This isn't necessary in Restricted mode or in the PWA/ Electron/ NWJS apps. In Restricted mode, the app will offer to download videos so you can view them in a different application. This is useful if your system doesn't support the WebP video format (e.g. the mobile UWP app).

PhET ZIMs: These science and maths simulations only work in ServiceWorker mode. There is currently a bug which causes the experiment/ simulation to be shifted by several pixels, making it hard to click on the experiment's controls. WORKAROUND: Please switch the Hide toolbars while scrolling option to never. This eliminates the pixel shift. You may also have to use the title search or ZIM Archive Index (press a space in title seaarch) to find the experiments, as there is an unresolved issue with displaying the ZIM's User Interface.

### Window and tab management

You can open ZIM links in a new browsable tab (or window) by setting the options in Configuration. Right-click (or double right-click if you set that option), ctrl-click, middle click and long press should all work. Somne contexts (e.g. mobile) don't support this option, or it works badly or very slowly. For those contexts, use the Download or open current article feature instead. With this feature, the tab is non-browsable, but you can save the page to PDF or print it, etc., from that tab.

Help! - when I click on an external link it gets blocked! Don't panic, this is the Content Security Policy potecting you. You have probably activated Service Worker mode. To open external web sites, you need to turn on the option Open links in a new tab (in ServiceWorker mode). In Restricted mode, external links will open in a new tab/window regardliness of this setting. Additionally, please note that your browser's popup blocker may be interfering with options that open new tabs or windows. When asked, enable popups always for the app (if you trust Kiwix), and then reload the app.

In most browsers and frameworks you can set the app to full-screen mode using the option in Configuration, and in Chromium and Firefox browsers you can also lock the orientation of the app while it is in full-screen mode. Because the browser may throw you out of full-screen mode, for example, when you select an archive or when opening a new window, you may need to click in the app to re-activate full-screen mode. Full-screen mode needs to be activated by a user gesture: it is not possible to activate it automatically.

### Browser support

We test the app frequently on older browsers and operating systems. The app will usually detect which features don't work on a given browser, and disable them or work around them. However, in some cases (e.g. Firefox <= 59), the app will set itself to Service Worker mode, but this mode will silently fail. If affected, please try switching the app to Restricted mode (see below).

We have a version of this app using the NWJS framework that runs on Windows XP/Vista, and there are Electron apps for 32bit and 64bit Linux, macOS and Windows 7/8/10/11, also on ARM64, as well as a UWP (Store) app.

The PWA is fully supported for offline use in modern browsers on Android, iOS, macOS, Linux and Windows. On Android, Linux, macOS and Windows, using Chrome/Chromium browsers (including Edge and Samsung Internet), you can install the PWA using a button in Configuration for a near-native experience. On iOS in Safari, you can add the PWA to your Home screen, which has the same effect.

#### Officially supported:

- Firefox >= 60 on all operating systems (but see note about Android*)
- Edge Chromium >= 79
- Chrome/Chromium >= 59 (and many browsers based on Chromium, e.g. Opera, Samsung Internet)
- Edge Legacy 18, including UWP
- Safari on iOS

* The Firefox on Android app only works well with files stored in the Origin Private File System. Picking files from the user-visible file system suffers from a Firefox bug whereby the app attempts to load the picked file into memory, which can take a very long time and may fail.

#### Deprecated

Although deprecated, we will keep support for as long as is practical:

- Internet Explorer 11 (Restricted mode only, no offline use of PWA)
- Edge Legacy <= 17 (Restricted mode only, no offline use of PWA)
- Firefox 45-59 (some versions require you to switch manually to Restricted mode)
- Chromium 49-58 (some versions only run in Restricted mode)

### Express server (Electron app)

When running in the Electron framework, this app includes a built-in Express server that allows you to access the app from any browser on your local device or network. The server hosts the app's code, and you can then select and access your own ZIM archives through the browser interface. This is useful for when you want to serve the app to other devices on a closed network that does not have external Internet access.

To access from another browser on the same device:

1. On the Home tab, the app displays a localhost link (e.g., http://localhost:3000)
2. Open any browser on the same device and navigate to this address
3. You can then select your ZIM archives in the browser as normal

To access from another device on your local network:

1. On the Home tab, check the "Allow external network access" option (this session only)
2. Your Firewall may prompt you to allow network access - approve this to enable external connections
3. The app will display links showing the local IP address where you can access it (e.g., http://192.168.1.100:3000)
4. On another device on the same network, open a web browser and navigate to the displayed address
5. You can then select your ZIM archives in the browser (they need to be accessible from that device)
6. To access ZIM archives stored on the host device, share them via a network file share so they can be selected from the remote browser

You can customize the port number in Configuration > Expert Settings. The default port is 3000.

Important notes:

- Because access from other devices is over HTTP (not HTTPS), the app will run in Restricted mode (see below) when accessed from a browser (this is not the case if using localhost)
- Only enable external network access when you trust all devices on your local network
- The server only allows connections from your local network (private IP ranges), not from the public internet
- External access is disabled by default for security and only applies to the current session

### Technical information

Depending on your browser or framework, this app may be capable of running in two different modes, which we call "ServiceWorker Mode" and "Restricted mode". There is a toggle under Performance/compatibility settings in Configuration. Here is an explanation of what these modes do:

- ServiceWorker Mode (defualt): This mode, as its name implies, requires that the browser or framework be capable of installing a Service Worker. It works by intercepting the browser or framework's Fetch calls (network requests) and supplying the requested content from the ZIM. This mode requires no DOM traversal, and the content is read and supplied as-is from the archive. Dynamic content (e.g. JavaScript) and proprietary UIs are fully supported in this mode. It can feel initially a little slower while commonly used assets are being cached, but it soon equals Restricted mode in speed, at least in modern browsers. However, older browsers such as IE11 do not support this mode, and the app must be running in a secure context (https:, localhost, or certain browser extensions). Please be sure only to open ZIMs from sources you trust in this mode: see Security for more information.
- Restricted mode: This mode prevents attached scripts from running in the iframe, so it is useful for checking the static content of a ZIM before you allow scripts to run. It is also compatible with older browsers or frameworks that cannot run Service Workers.The mode has limitations which mean that only static content can be displayed, such as that found in Wikipedia / WikiMedia archives and (for now) Stackexchange. It is a way of inserting articles extracted from the ZIM into the DOM (browser document) by injecting the content into an iframe or tab. We then use native DOM methods to parse the article's HTML and insert required assets (images, stylesheets, event listeners for hyperlinks, etc.). On old devices, DOM traversal can be slow, but it is compensated for because we do not extract or run JavaScript assets (which would be technically extremely complicated). As a result, for WikiMedia archives this mode is usually quite fast. On the downside, ZIMs that have a proprietary dynamic UI (such as Gutenberg or TED talks) are only partially supported in this mode: the UI does not work, but articles can be searched for and loaded from the search bar.

### Feedback / helping / contributing

This application is still a work in progress. There are bugs that need fixing and improvements that need to be implemented. Suggestions and patches/pull requests are welcome: the source code is on github. The Kiwix JS Windows issue tracker is on GitHub too, though also check the tracker for Kiwix JS as a lot of the development is done for both apps.

Alternatively, you can send your feedback by email .

In all cases, please give as much detail as you can: which device you are using, which version of Kiwix, which archive, which articles etc.

If you like the Kiwix project and use it, please consider giving donations:

- to the Wikimedia foundation, to help maintaining their servers and article contents. See the donation page
- to Kiwix, to help maintaining the ZIM files and applications. There is a donation button in the home page of kiwix.org

You can also help by:

- Adding articles or improving the existing ones, by editing online Wikipedia articles
- Participating in the Kiwix project

### Credits

Thanks are due to:

- Kelson and all the Kiwix community for welcoming peter-x, mossroy, jaifroid and sharun-s onto this project
- Wikipedia teams and contributors for helping to spread knowledge to everybody
- All the developers of libraries and tools we use for releasing them as Free software (see Licence paragraph)

### Licence information

Copyright 2013-2023 Jaifroid, Mossroy, Peter-x and other contributors
Jaifroid for adaptation and development of the app on the Universal Windows, Electron, NWJS and PWA Platforms
This application is licensed under the GPL v3 licence:
Kiwix is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public Licence as published by
the Free Software Foundation, either version 3 of the Licence, or
(at your option) any later version.
Kiwix is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public Licence for more details.
You should have received a copy of the GNU General Public Licence
along with Kiwix (file LICENSE-GPLv3.txt). If not, see https://www.gnu.org/licenses/

Main libraries and resources used:

- Bootstrap 4.6.2, released under an Apache Licence 2.0
- Font Awesome 5.15.4, released under the Font Awesome Free License
- rollup.js 3 for bundling this app, released under an MIT licence
- QUnit 2, released under an MIT Licence
- Kiwix logo from kiwix.org, released under a Creative Commons Attribution Share Alike Licence
- OpenZIM specifications from www.openzim.org, released under the Creative Commons Attribution Share Alike Licence
- Emscripten to generate XZ, ZSTD and libzim decompressors in JavaScript: https://github.com/kripken/emscripten, released under the MIT Licence
- XZ Embedded (the XZ library converted to Javascript with Emscripten), in public domain
- The Zstandard library, released under a BSD Licence and a GPLv2 Copying Licence
- KaTeX for typesetting mathematical and chemical equations, released under the MIT licence
- Hilitor for finding and hilighting text inside an article, released under this licence
- DarkReader for converting Web pages to dark mode, released under an MIT Licence
- The Web Archive Browsing Advanced Client and Wombat Client-Side Rewriting Library from the WebRecorder ReplayWeb project, released under a GNU Affero General Public Licence

### Other platforms/versions

Other Kiwix clients exist on various platforms. See the official site : https://www.kiwix.org/.

## Configuration

Version: Kiwix JS [check for updates]

Open this app in your browser:
Allow external network access (this session only)

For instructions and usage guide, please see the About tab (top right).

Packaged ZIM archive:

Current archive:

Download more archives from the Archive Library.

Archives found on this device (tap "Select storage" to rescan):

There were no ZIM file(s) found in the selected location!

Pick ZIM archive(s):

For multiple or split archives:

Please choose the location of your ZIM archive or drag-and-drop the file(s) here.
For a split archive (.zimaa, .zimab, etc.) you must select all the split parts.

Use Private File System [info] (default for Firefox and Android)
Select ZIM files or drag and drop

#### Download library

| Opens library of archives for download: Warning: this will use data

Allow Internet access? and check for updates

#### Display settings

Display size, theme and orientation
Full-screen mode / lock orientation:
Change font size for the User Interface:
(to change article font size, tap and )
100%
Set dark mode for User Interface: [ ] (auto mode uses OS Settings if available) Set dark theme for articles: [ ] (for Wikimedia, Gutenberg and Stackexchange ZIMs only) Use the DarkReader plugin (experimental: should work with wider range of archive types)
Use simple inversion for dark theme (may work with some other archive types) Force use of legacy dark theme (for older Wikimedia ZIMs) Show toolbar buttons: [ ] (select to show random or theme buttons in toolbar) Fix UI bug with secondary displays (increases load and resize time, turn off if not needed)
Display style (mobile, desktop)
Default ZIM style (for Wikimedia ZIMs) Use Wikimedia desktop style (and transform if necessary) Use Wikimedia mobile style (and transform if necessary) Use locally cached Wikimedia styles (recommended: also removes unused JS) Remove max page width restriction: [ ] (useful for recent Wikipedia archives)
Display hidden block elements: [ ] (for Wikimedia ZIMs: shows elements that are hidden in mobile style)
Open all headings (for WikiMedia ZIMs: sets the state of collapsible headings in mobile style only)
Image and map settings
Display images if any (if hidden, tap the blue area to display one-by-one)
Allow image manipulation (may interfere with dynamic content)
In Wikipedia ZIMs, hyperlink images to high-res Wikimedia versions (click image to open the external site in a new window, disabled for imagemaps and landing page) Use online OpenStreetMap for map pins instead of offline Windows Maps (for some Wikipedia and English / German Wikivoyage)
Navigation, search and other
Hide toolbars while scrolling: [ ] (scroll slightly up to reveal) Move navigation buttons to top toolbar (note that Kiwix icon acts as Home button)
Alphabetical ZIM Archive Index:
Start character of alphabet: (use capital letters if they exist in your locale)
End character of alphabet: (these are used to set appropriate alphabet for the Archive Index)
Title search:

Wildcards `.*` or `.+` are permitted, e.g. `list.+medieval`, but see usage

Select max number of search results: (higher values increase search time)

Add snippets to libzim fulltext search (if available) Open links in a new tab with right-click, ctrl-click, middle-click or long-press
Open in new window instead
Use double right-click to open window/tab
Download or open current article via breakout icon (self-contained, but not browsable)

#### Privacy settings

Control of browsing data
Reopen last-visited page on next app launch (turn off if researching sensitive topics) Warn before opening external links (recommended)

To clear all data from the app, consider a full app reset after your browsing session (see under Expert settings)

#### Performance / compatibility

Caching and preview settings

Speed up the display of articles by caching assets:

Cache assets (recommended) Do not cache assets (empties caches: for low-memory devices)
Show a popover preview of Wikipedia / Wkivoyage articles when hovering over links (limited functionality in Restricted mode)
Mathematical and chemical equations and symbols
Typeset TeX equations with KaTeX (recommended: very fast, but not all symbols may be supported in all languages; will use SVG fallbacks if TeX string not available) Use SVG fallback images (slow and memory-hungry, but will display all symbols)
Content injection mode

See About (Technical settings) for an explanation of the difference between these modes:

ServiceWorker (recommended, supports dynamic content and inline JavaScript) Restricted (no dynamic content, compatible with older browsers and frameworks)
Display hidden ZIM archive selectors
Display selectors for files and folders : This is for downloading other ZIM archives.

#### Expert settings

Modify default behaviours
Warn before leaving page with loaded archive (prevents accidental closing/reloading) Disable drag-and-drop (in case it is causing anomalies) Enable source verification of new files (recommended: you will only be prompted the first time you open a ZIM) Enable automatic updates for PWA (recommended: you will be updated without being prompted)
Troubleshooting and development
Permanently hide active content warning (for experienced users) Force / disable libzim W/ASM for reading full-text index:

Warning! Disables OS/ZIM checks and may make title search and article reading unresponsive!

Also use selected libzim for reading ZIM content (unstable) Use legacy method for reading Zimit-based archives (may be faster on some systems)
Customize the localhost port when accessing this app from a browser:
Developer Mode (disables offline use of PWA!)

Reset the app to default settings and erase all caches:

API Status

#### Welcome to Kiwix JS PWA!

To use this app, you need to load a ZIM archive first. Go to Configuration and use the file or folder selector to pick an archive. You can also download an archive using the in-app library (in Configuration).

For usage instructions and more information, please go to the About tab .

Once you have picked an archive, you can search its contents by typing in the above search field. It will suggest articles starting with the letters you type.