Widoco Local File Tip

Widoco is an excellent tool for generating readable HTML documentation from an OWL ontology. However, there is one common “gotcha” that often surprises people the first time they use it.

The Local File Gotcha

If you generate Widoco documentation and save it directly to your hard drive, you may be able to open the main index.html page in your browser, but much of the content may appear blank.

This can be confusing because it looks as if Widoco did not generate the documentation correctly. In most cases, that is not the problem. The documentation is there. The issue is that modern browsers restrict how local HTML pages can load local JavaScript and CSS files.

In other words, this is not really a Widoco problem. It is a browser security issue.

The Symptom

You may see something like this:

• The main Widoco page opens.
• The basic page frame appears.
• Some sections are blank or do not expand.
• The ontology content appears to be missing.

The generated files are usually fine. The browser is simply blocking some of the local files that Widoco needs in order to display the documentation correctly.

The Simple Fix: Use GitHub Pages

The simplest solution is to host the Widoco output somewhere it can be served over HTTP or HTTPS.

For many ontology projects, GitHub Pages is the easiest option. It lets you publish static HTML files directly from a GitHub repository, without setting up a separate web server.

A typical workflow is:

1. Run Widoco and generate the documentation folder.
2. Copy the generated output into your GitHub repository.
3. A good convention is to place the output under a /docs folder.
4. In the repository settings on GitHub, enable GitHub Pages.
5. Configure GitHub Pages to publish from the /docs folder.
6. GitHub will host the documentation at a public URL, such as:

https://yourname.github.io/your-repo/