How to Put a DoView Board Collection Onto the Internet

This page explains how to put a DoView Board Collection onto the internet using GitHub Pages.

GitHub Pages is a free way to publish simple web pages from a GitHub repository. A DoView Board Collection can be put online this way because it is made up of ordinary files: HTML files and JSON files.

You do not need to run a server. You do not need a database. You put the files into GitHub, turn on GitHub Pages, and GitHub publishes the collection as a website.

The simple version

A DoView Board Collection usually has this structure:

boards/
  index.html
  collections.json

  nz-government/
    index.html
    collection.json
    nz-government-targets-doview-board.html
    nz-ministry-of-education-doview-board.html
    other-board-files.html

  large-companies/
    index.html
    collection.json
    toyota-doview-board.html
    walmart-doview-board.html
    anthropic-doview-board.html

The main page is:

boards/index.html

That page reads:

boards/collections.json

The collections.json file lists the collections. For example, it might say that there is a collection called “NZ Government” and that its folder is:

nz-government/

Each collection folder then has its own page:

boards/nz-government/index.html

That page reads:

boards/nz-government/collection.json

The collection.json file lists the actual DoView Board files in that folder.

What you normally need to upload

To put a DoView Board Collection online, upload these files to GitHub:

boards/index.html
boards/collections.json

Then, for each collection, upload a folder like this:

boards/name-of-collection/index.html
boards/name-of-collection/collection.json
boards/name-of-collection/your-doview-board-file.html

For example:

boards/nz-government/index.html
boards/nz-government/collection.json
boards/nz-government/nz-government-targets-doview-board.html

What each file does

boards/index.html

This is the collection-of-collections page.

It shows the list of collections, such as:

NZ Government
European Union
Large Companies
Research Domains
Generic Initiatives

You do not normally edit this file. It is a template.

boards/collections.json

This file tells the main page which collections exist.

For example:

{
  "version": "v1.2.7",
  "collections": [
    {
      "title": "NZ Government",
      "href": "nz-government/",
      "count": "1 apex · 20 agency boards"
    },
    {
      "title": "Large Companies",
      "href": "large-companies/",
      "count": "3 boards"
    }
  ]
}

Update this file when you:

add a new collection folder
rename a collection folder
remove a collection folder
change the number of boards shown on the main page

boards/name-of-collection/index.html

This is the page for one collection.

For example:

boards/nz-government/index.html

It displays the boards listed in that folder’s collection.json.

You do not normally edit this file. It is also a template.

boards/name-of-collection/collection.json

This file lists the DoView Boards in one collection.

For example:

{
  "version": "v1.2.7",
  "title": "NZ Government DoView Boards",
  "subtitle": "A DoView Collection — illustrative agency boards",
  "status": "Illustrative only – Not Endorsed",
  "currentTitle": "NZ Government",
  "boards": [
    {
      "title": "Ministry of Education",
      "acronym": "MoE",
      "file": "nz-ministry-of-education-doview-board.html"
    }
  ]
}

Update this file when you add, remove, or rename a DoView Board inside that collection folder.

Important rule

There are two different JSON files:

collections.json

and:

collection.json

They do different jobs.

Use:

boards/collections.json

to list the collections.

Use:

boards/name-of-collection/collection.json

to list the DoView Boards inside one collection.

So, if you add a new DoView Board file to a subfolder, you usually update the subfolder’s:

collection.json

not the top-level:

collections.json

Only update collections.json if you are adding or changing a whole collection.

How to add a new DoView Board to an existing collection

Suppose you want to add a new board to:

boards/nz-government/

Do this:

1. Upload the new DoView Board HTML file into:

boards/nz-government/

2. Open:

boards/nz-government/collection.json

3. Add a new entry for the board.

For example:

{
  "title": "Ministry of Health",
  "acronym": "MoH",
  "file": "nz-ministry-of-health-doview-board.html"
}

4. Make sure the filename in the JSON exactly matches the actual HTML filename.

5. Save the file.

6. Wait a minute or two for GitHub Pages to update.

How to add a new collection

Suppose you want to add a new collection called:

Health Sector

Create a new folder:

boards/health-sector/

Put these files in it:

boards/health-sector/index.html
boards/health-sector/collection.json
boards/health-sector/your-board-file.html

Then update:

boards/collections.json

Add an entry like this:

{
  "title": "Health Sector",
  "href": "health-sector/",
  "count": "1 board"
}

The href must match the folder name.

If you do not know how to use GitHub

GitHub is a website where you can store files online. GitHub Pages can then publish those files as a website.

For a DoView Board Collection, you mainly need to know how to do four things:

create a repository
upload files
edit a file
turn on GitHub Pages

Step 1: Create a GitHub account

Go to GitHub and create a free account.

Once you have an account, sign in.

Step 1: Create a GitHub account

A repository is just a folder of files on GitHub.

Create a new repository. Give it a simple name, for example:

doview-board-collection

Make the repository public if you want to use GitHub Pages for free.

Step 3: Upload your files

Inside the repository, upload your DoView Board Collection files.

The structure should look like this:

boards/
  index.html
  collections.json

  example-collection/
    index.html
    collection.json
    example-doview-board.html

GitHub will show these as folders and files.

Step 4: Turn on GitHub Pages

In your repository:

1. Go to Settings.

2. Find Pages.

3. Under Build and deployment, choose the branch that contains your files, usually:

main

4. Save the setting.

GitHub will give you a website address. It will usually look something like:

https://your-github-name.github.io/your-repository-name/

Your DoView Board Collection will usually be at:

https://your-github-name.github.io/your-repository-name/boards/

Step 5: Check the website

Open the GitHub Pages website address in your browser.

Then go to:

/boards/

You should see the collection-of-collections page.

Click a collection. You should see the boards in that collection.

Click a board. The DoView Board should open.

Common mistakes

The card appears, but the board does not open

Check that the filename in collection.json exactly matches the real HTML filename.

For example, this:

"file": "nz-ministry-of-education-doview-board.html"

must match this file exactly:

nz-ministry-of-education-doview-board.html

Even one wrong letter can break the link.

A collection does not open

Check that the folder name in collections.json is correct.

For example:

"href": "nz-government/"

must match the folder:

boards/nz-government/

The page says it cannot load JSON

Check that the JSON file is in the same folder as the index page that uses it.

This page:

boards/index.html

needs:

boards/collections.json

This page:

boards/nz-government/index.html

needs:

boards/nz-government/collection.json

GitHub Pages has not updated yet

Sometimes GitHub Pages takes a minute or two to update. Wait briefly, then refresh the page.

Using AI to help update the files

You can use AI to help update the JSON files.

For example, you can say:

Here is my collection.json file. Please add this new DoView Board to it. Keep the same JSON structure and return the full updated file.

Or:

Here is my collections.json file. Please add a new collection called Health Sector with the folder health-sector/.

Then copy the updated JSON back into GitHub and save it.

Summary

To publish a DoView Board Collection:

put the files into GitHub
turn on GitHub Pages
open the /boards/ page

To update the collection:

add the board HTML file
update the right JSON file
save the change
check the website

Most of the time, you do not need to edit the HTML templates. You only need to update the JSON files.