`docs.mbari.org`

Welcome to the docs.mbari.org system!

The docs.mbari.org server can automatically build and deploy Mkdocs based websites from git repositories. As a user of this system, you just need to add a "webhook" to your git repository so that whenever you check in updates, docs.mbari.org will take care of building and reflecting the changes in either an externally facing location or an internally-only available site.

What packages are installed?

Please see https://docs.mbari.org/internal/_/pip_list.txt, which is updated regularly. Contact us (IE group) if your site needs additional packages.

Adding Your Repository

GitHub and Bitbucket repositories are supported.

GitHub:
- Any public repository
- Only those under the github.com/mbari-org organization for private repositories.
Bitbucket:
- Any public repository
- Only those under bitbucket.org/mbari for private repositories.

To enable this service for your Mkdocs-based repository, visit the relevant Webhook section in your repository settings to add one with the following URL (it doesn't matter what you name it):

https://docs.mbari.org/dochook/docs-mbari-org-webhook

Note

For GitHub, make sure you also select Content type: application/json.

That's it.

By default, it is assumed that the root of your repository corresponds to the expected Mkdocs layout, which is:

 /mkdocs.yml
 /docs/
      index.md
      ...

But you can override the actual base directory corresponding to your Mkdocs location, see below.

Site Visibility

If your repository is public, the deployed site will, by default, be open to the world. If it is private, the site will, by default, be deployed under https://docs.mbari.org/internal/, which is only available to machines accessing it from the MBARI network (i.e. VPN'd in or on site).

Example: If your repository is https://bitbucket.org/mbari/foo, then:

If repo visibility is	Site deployed as
private	`https://docs.mbari.org/internal/foo`
public	`https://docs.mbari.org/foo`

You can also override this behavior as explained below.

Per Repository Configuration

To override some generation settings, you can create a file named .mbaridoc.json and put it in the root of your repository. In that file you can use the following optional entries:

docdir: the subdirectory under your repository corresponding to the actual MkDocs location, that is, the subdirectory containing mkdocs.yml. By default, this is ., meaning the root of your repository. If you specify this option, say:
```
{
  "docdir": "doc"
}
```
then the relevant layout starting from the root of your repository should look like so:
```
/doc/mkdocs.yml
/doc/docs/
          index.md
          ...
```
Note

If using the docdir, and not indicating always_generate as true (see below), the webhook will process your site only if the last commit involves any changes under the given directory (/doc/ in the above example).
always_generate: If you set this to true, the site will be generated regardless of whether the last commit changes involve the indicated docdir.
destination: the name of the directory where you want it deployed, which will end up being the latter part of the URL where the site will be available. By default, the destination name will be the same as the simple name of the repository.

Alert

Please make sure the desired destination does not clash with some other site!
public: Regardless of the visibility of your repository, you can determine the visibility of the generated site with this setting: true for public, false for private.

As an example, https://bitbucket.org/mbari/tethysdash-doc is the repository for the TethysDash documentation. Although the repository itself is private, the generated site is to be public, and actually under a different deployed location (https://docs.mbari.org/tethysdash). To accomplish this, here is the contents of the associated .mbaridoc.json:

{
  "destination": "tethysdash",
  "public": true
}

Note

If you are enabling the editing of pages via links to the remote repository, that is, by setting repo_url in your mkdocs.yml, you may need to also set the edit_uri property, in particular, if you are using a non-default docdir. As an example, the mkdocs.yml of this meta-doc site that you are looking at right now, has:

site_name: MBARI Docs Generation
repo_url: "https://github.com/mbari-org/docs-mbari-org-webhook-doc/"
edit_uri: "src/main/mkdocs/docs/"

More details about edit_uri at the mkdocs site.

Site Listing

Depending on its visibility, your site will be listed in one of these places:

Public sites: https://docs.mbari.org/
Internal sites: https://docs.mbari.org/internal/

These listings are generated automatically.

The title of each site (captured with the site_name property in mkdocs.yml) is used for the listing. Along with the title, a description will also be shown if available for the site. You can capture such description using MkDocs as follows:

Add the meta markdown extension in your mkdocs.yml:
```
markdown_extensions:
  - meta
  - ...
```
In your main markdown page (the one associated with the "home" of your site), put the following at the top:
```
---
description: A nice short description for my site!
---
```

Local Development

As an MkDocs site, and except probably for straightforward adjustments, you may want to have the following running on your machine while putting together your documentation:

mkdocs serve

With your browser pointing to http://127.0.0.1:8000/ you will see any updates immediately¹ reflected as you make changes to your markdown files, or any associated resources.

Styling

General Styling

If you want to align your mkdocs styling with other sites hosted on docs.mbari.org, consider using the following in your mkdocs.yml:

theme:
    name: material
    logo: https://docs.mbari.org/imgs/mbari-logo.png
extra_css:
    - https://docs.mbari.org/css/mbari.css

Misc Styling

The following are just some quick tips regarding alternative font families. Of course, please use and adjust as you see fit.

You can incorporate the settings via an extra css file, say extra/extra.css, to be indicated in your mkdocs.yml:

extra_css:
    - extra/extra.css

Main font

There are plenty of options to choose from. Here, just a couple of examples:

MerriweatherOpen Sans Condensed

@import url(https://fonts.googleapis.com/css?family=Merriweather:300);
body {
  font-family: 'Merriweather', serif;
  font-weight: 300;
}

@import url('https://fonts.googleapis.com/css2?family=Open+Sans+Condensed:wght@300');
body {
  font-family: 'Open Sans Condensed', 'Serif';
  font-weight: 300;
}

Code font

For sites involving code-like snippets (scripts, program output, configuration files, etc.), you may want to consider options like the following (again, plenty of options out there):²

IosevkaFira Code

@import url(https://docs.mbari.org/css/iosevka-custom/iosevka-custom.css);
code, tt {
  font-family: 'Iosevka', 'Roboto Mono', monospace;
  font-weight: 400;
  font-variant-ligatures: none;
}

Reference: https://typeof.net/Iosevka/
A custom Iosevka build has been made according to these instructions, and deployed on the docs machine to facilitate reuse. (Iosevka's license is available here.)

@import url(https://cdn.jsdelivr.net/gh/tonsky/FiraCode@4/distr/fira_code.css);
code, tt {
  font-family: 'Fira Code', 'Roboto Mono', monospace;
}

Reference: https://github.com/tonsky/FiraCode#browser-support

Enabling dark mode

For the general set of options, see the MkDocs-Material Changing the colors section.

In short, you can allow the user to optionally select dark mode for your site as follows.³

Add the palette section below in your mkdocs.yml:

theme:
  name: material
  logo: https://docs.mbari.org/imgs/mbari-logo.png
  palette:
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode
    - media: "(prefers-color-scheme: light)"
      scheme: light
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode

As set up above, the default palette will reflect the user's OS preference, who can then set the mode to light or dark as desired.

Depending on the contents of your site, some style settings may need to be adjusted for acceptable display in dark mode. Case in point, we've noted that links don't get very legible. We have addressed this issue with the following in an extra css file (like extra/extra.css):

[data-md-color-scheme=slate] {
  --md-typeset-a-color: #a6c1f1;
}

Well, maybe not as immediately depending on the number of documentation pages as noted with some sites. ↩
The site you are looking at uses the mentioned Iosevka custom build. ↩
The site you are looking at uses this feature as indicated. ↩