Official website for the Apache Ossie initiative. Built with MkDocs and Material for MkDocs.
Build the image once, then run:
docker build -t ossie-website .
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs ossie-websiteThe site will be available at http://localhost:8000.
Note: Docker Desktop for Mac does not reliably propagate filesystem events into the container, so live-reload may not work. Restart the container to pick up changes, or use Option 2 for a native dev experience.
Requires Python 3.9+.
pip install mkdocs-material mkdocs-macros-plugin "mkdocs-include-markdown-plugin[cache]"
mkdocs serveThe site will be available at http://localhost:8000 with live-reload.
mkdocs build # or: docker run --rm -v ${PWD}:/docs ossie-website buildOutput goes to the site/ directory (gitignored).
ossie-website/
├── mkdocs.yml # Site config: theme, nav, plugins, extensions
├── Dockerfile # Docker dev environment (Material + plugins)
├── data/
│ └── home.yml # Landing page content (text, members, updates)
├── hooks/
│ └── load_data.py # MkDocs hook: injects data/*.yml into Jinja2 context
├── overrides/ # MkDocs template overrides (custom_dir)
│ ├── home.html # Landing page template (extends main.html)
│ ├── content.html # Standard content page template (extends main.html)
│ ├── blog-post.html # Blog post template (removes author avatars)
│ └── partials/
│ ├── header.html # Custom single-bar header (replaces Material default)
│ ├── post.html # Blog index post excerpt (external link support)
│ └── external-link-icon.html # Reusable external-link SVG icon partial
└── docs/ # MkDocs content root
├── index.md # Home page (uses home.html template)
├── about.md # About page (Why Apache Ossie, Core Classes)
├── community.md # Community page (uses content.html template)
├── spec/ # Spec rendering (TODO: re-implement build-time import)
├── blog/ # Blog (managed by blog plugin)
│ ├── .authors.yml # Author definitions (name, description)
│ └── posts/ # Individual blog posts go here
└── assets/
├── images/
│ ├── ossie-logos/ # Apache Ossie brand logos (SVG)
│ ├── favicon.png # Browser tab icon
│ └── logos/ # Member company logos (PNG/SVG)
├── stylesheets/
│ ├── bootstrap.min.css # Bootstrap 5.3 (full framework)
│ ├── global.css # Apache Ossie design tokens, typography, color utilities
│ └── home.css # Landing page styles (backgrounds, hover effects)
└── javascripts/
└── home.js # Scroll animations (landing page)
Both templates extend Material for MkDocs' main.html, which provides the site
footer (social links, copyright) and all base functionality. The header is
provided by a custom partial (see below).
| Template | Purpose | Used by |
|---|---|---|
home.html |
Custom landing page with hero, cards, and sections. Overrides the tabs block to inject landing page content and hides the default MkDocs content area. |
docs/index.md |
content.html |
Standard content page. Inherits Material's default layout with sidebars, TOC, and content area — no block overrides needed. | docs/about.md, docs/community.md and any future content pages |
blog-post.html |
Blog post page. Identical to Material's built-in template but with author avatar/profile section removed. | Individual blog post pages |
Assign a template to a page via front matter:
---
template: content.html
---Stylesheets load in this order (configured in mkdocs.yml and templates):
bootstrap.min.css— Full Bootstrap 5.3 framework (loaded site-wide)global.css— Apache Ossie design tokens, typography classes, color utilities, Bootstrap overrides (loaded site-wide)home.css— Landing page visuals: section backgrounds, hover effects, accent borders (loaded only byhome.html)
All shared values are defined as CSS custom properties in global.css:
| Category | Examples |
|---|---|
| Colors | --ossie-primary-blue, --ossie-dark-blue, --ossie-navy, --ossie-light-blue, --ossie-ice-blue, --ossie-accent-green |
| Spacing | --ossie-spacing-xs through --ossie-spacing-xl |
| Typography | --ossie-font-body, --ossie-font-lead, --ossie-font-heading-sm through --ossie-font-heading-xl |
Utility classes: .ossie-text-dark-blue / -dark-gray / -gray / -primary.
Material for MkDocs applies its primary and accent colors via data-md-color-primary
and data-md-color-accent attributes on <body>. If no custom palette is
configured, it defaults to indigo — which would override any :root CSS variable
overrides because attribute selectors on body beat :root (on html) in the
cascade.
To use our brand colors correctly, mkdocs.yml sets:
palette:
scheme: default
primary: custom
accent: customThis causes Material to render data-md-color-primary="custom" on <body>,
which doesn't match any built-in palette rules. Our colors are then defined in
global.css under matching attribute selectors:
[data-md-color-primary=custom] {
--md-primary-fg-color: #29B5E8;
--md-primary-fg-color--light: #56C4EF;
--md-primary-fg-color--dark: #043464;
--md-typeset-a-color: #043464;
/* ... */
}
[data-md-color-accent=custom] {
--md-accent-fg-color: #56C4EF;
--md-accent-fg-color--transparent: rgba(86, 196, 239, 0.1);
}Important: Do not try to override
--md-primary-fg-coloror--md-typeset-a-colorin:root— Material's built-in[data-md-color-primary]attribute selectors on<body>will always win. Use the[data-md-color-primary=custom]selector instead.
The site uses a custom header partial (overrides/partials/header.html) that
replaces Material for MkDocs' default two-bar layout (header + tabs) with a
single bar:
| Logo Home About Spec Community Blog GitHub (search) |
Key details:
navigation.tabsis kept inmkdocs.ymlbut the rendered.md-tabsbar is hidden withdisplay: none. This preserves Material's sidebar scoping (subpage sidebars only show children of the active top-level section).navigation.tabs.stickyis removed — it's unnecessary since we own the header template entirely.- The header uses a frosted-glass effect (
backdrop-filter: blur(10px)with semi-transparent white background) and a drop shadow. - Nav links and search icon use dark-blue text to contrast with the translucent white background.
- On mobile (below Material's
76.25embreakpoint), the nav links hide and a hamburger icon appears, opening Material's built-in drawer/sidebar. - Search is preserved by including
partials/search.htmlinside the same<header>element, which keeps Material's CSS toggle mechanism working. - Since this fully replaces
header.html, upstream Material updates to the header will not be inherited automatically.
Landing page content lives in data/home.yml, not in mkdocs.yml. A custom
MkDocs hook (hooks/load_data.py) loads all YAML files from data/ and injects
them as global Jinja2 template variables. This means home.html can reference
variables like {{ hero.title }} and {{ members.list }} directly.
The same hook also scans docs/blog/posts/ for blog post front matter, sorts by
date (newest first), and injects the top 3 as latest_posts. The homepage
"Latest Updates" section renders these cards automatically — both internal posts
and external posts (identified by an external_url front matter field) appear
here and on the /blog/ index.
Build-time rendering of the Apache Ossie specification is not yet implemented. The Spec
nav link currently points directly to the
spec on GitHub.
See docs/spec/README.md for the TODO.
You do not need to edit HTML to change landing page content. All text,
members, updates, and other content is stored in data/home.yml. The template
reads these values and renders them automatically.
Open data/home.yml and find the section you want to edit. For example, to
change the hero banner headline:
hero:
title: "Your new headline here"
subtitle: "Your new subtitle here"- Place the logo file (PNG or SVG) in
docs/assets/images/logos/ - Add an entry to the
members.listarray indata/home.yml:
members:
list:
# ... existing members ...
- name: "New Company"
logo: "new-company-logo.png"Apache Ossie design tokens live in :root in docs/assets/stylesheets/global.css:
:root {
--ossie-primary-blue: #29B5E8;
--ossie-dark-blue: #043464;
--ossie-accent-green: #07A77F;
/* ... etc ... */
}If you change a color that is also mapped into Material's palette (primary blue,
light blue, dark blue), update the corresponding values in the
[data-md-color-primary=custom] and [data-md-color-accent=custom] blocks in
the same file. See the "Material for MkDocs Custom Palette" section above.
- Create a
.mdfile indocs/ - Add front matter pointing to the
content.htmltemplate:
---
template: content.html
title: Page Title
---- Add it to the
nav:section inmkdocs.yml
The page will automatically get the site header, footer, navigation sidebar, table of contents, and all global styles.
The nav: section in mkdocs.yml controls the header tabs and sidebar menus:
nav:
- Home: index.md
- About: about.md
- Spec: https://github.com/apache/ossie/blob/main/core-spec/spec.md
- Community: community.md
- Blog: blog/
- GitHub: https://github.com/apache/ossieEach top-level item becomes a nav link in the header. Nested items appear in the left sidebar when that section is active.
---
template: content.html # Which template to use
title: Page Title # Browser tab title
description: A brief summary # Search engines and social previews
hide:
- navigation # Hide the left sidebar
- toc # Hide the table of contents sidebar
---Warning —
hide: [navigation]and the homepage: Do not usehide: [navigation]ondocs/index.md. Material for MkDocs implements this by adding an HTMLhiddenattribute to.md-sidebar--primary, which removes the sidebar from the DOM on all screen sizes — including mobile, where it serves as the hamburger drawer menu. The homepage template (home.html) already hides the sidebar on desktop via a CSS media query, sohide: [navigation]is redundant there and breaks the mobile drawer. Usehide: [toc]only.
Blog posts are powered by the Material for MkDocs
blog plugin, which
automatically generates the index, archive, and category pages. Posts appear at
/blog/ on the site.
- Create a new
.mdfile indocs/blog/posts/(the filename becomes the URL slug unless overridden) - Add the required front matter (see below)
- Write your content in Markdown
Every post must include date and authors. Other fields are optional but
recommended:
---
date: 2025-06-15 # Publication date (YYYY-MM-DD)
authors:
- ghost # One or more author IDs from .authors.yml
categories:
- Announcements # Groups the post in a category page
tags:
- osi # Freeform tags
- open-source
description: >- # Used in social previews and search results
A short summary of the post.
draft: true # Set to true to hide the post from production
---Posts published on partner websites (e.g. Snowflake, Databricks) can be
represented as thin markdown files. Add an external_url field to the front
matter — this signals to the homepage and blog index that the post links out
to an external site:
---
date: 2025-03-12
authors:
- snowflake
categories:
- Announcements
description: >-
A brief summary of the external article.
external_url: https://www.snowflake.com/en/blog/example-post/
---
# Post Title
Brief summary of the article.
<!-- more -->
Read the full post on [Snowflake's blog](https://www.snowflake.com/en/blog/example-post/).External posts appear in the blog index and homepage "Latest Updates" cards with an external link icon beside the title. The "Continue reading" link on the blog index points to the external URL.
Place an <!-- more --> separator in your post. Everything above it becomes the
excerpt shown on the blog index page. If omitted, the full post body is shown.
# Post Title
This introductory paragraph appears on the blog index as the excerpt.
<!-- more -->
The rest of the post only appears on the full post page.Authors are defined in docs/blog/.authors.yml. Each entry has an ID (used in
post front matter) and a display name:
authors:
jsmith:
name: Jane Smith
description: Apache Ossie Working Group Lead
avatar: https://example.com/jsmith.pngThe avatar field is required by the blog plugin — the build will fail
without it. Use a URL to a headshot or a placeholder image.
To add a new author, add an entry to this file and then reference the ID in your
post's authors list. See the Material for MkDocs
authors documentation
for additional fields and links to social profiles.
The blog plugin is configured in mkdocs.yml under plugins. Current settings:
| Setting | Value | Effect |
|---|---|---|
blog_dir |
blog |
Posts live under docs/blog/ |
blog_toc |
true |
Post titles appear in the TOC on the index page |
post_date_format |
long |
Dates render as e.g. "June 15, 2025" |
post_url_format |
{slug} |
Post URLs are /blog/<slug>/ (no date prefix) |
This site loads the full Bootstrap 5.3 CSS framework alongside Material for MkDocs. Key things to be aware of:
- Bootstrap loads globally — its reboot and utility classes affect all pages, not just the landing page.
- Material for MkDocs scopes its styles — content typography is inside
.md-typeset, so Bootstrap's reboot generally doesn't conflict with doc/blog pages. - Button classes — Bootstrap's
.btn,.btn-primaryetc. are used instead of custom button styles. Apache Ossie brand colors are applied via--bs-btn-bgand related CSS custom properties inglobal.css. - Link styles —
--bs-link-color,--bs-link-color-rgb, and--bs-link-decorationare overridden inglobal.cssto match the Apache Ossie palette and prevent unwanted underlines. Material link colors are set via the custom palette system (see "Material for MkDocs Custom Palette" above).
- MkDocs documentation
- Material for MkDocs documentation
- Material for MkDocs — Setting up navigation
- Material for MkDocs — Blog plugin
- Material for MkDocs — Customization
- Bootstrap 5.3 documentation
- mkdocs-include-markdown-plugin
All content in this repository — including code and documentation — is licensed under the Apache License 2.0.