Administrator access

Enter the site-wide access code to view pgfacts.org.

Simple gate for now; not a full login system.
Contact Us
Work In Progress: technical/pgfacts-site-guide.md How the site is structured and maintained.
PG Facts Site Guide Where navigation, layouts, tiles, and site settings are maintained. Managing Pages How to add pages and keep them aligned with the shared topic structure. Rendering Content How content is displayed as reusable cards on web pages.

PG Facts Site Guide

This is the working guide for maintaining the PG Facts Documentation site. This explains where the navigation comes from, which files control page content, how topic tiles are built, and what to edit when you want to add or change descriptions.

Site overview

Every page has the same layout structure: the site header, a breadcrumb and short description bar, the topic tile bar, and the page content from an MD file. The Markdown page supplies its own title in the content as the first line with a single #.

The main layout files are:

File Description
_layouts/default.html Includes the site header and page banner around the page layout.
_layouts/page.html and _layouts/home.html Place the shared topic tiles before the page content.
_includes/site-header.html Renders the logo and menu from _data/navigation.yml.
_includes/page-banner.html Renders the breadcrumb and page description.
_includes/topic-tiles.html Chooses topic tiles from each topic's _data/<topic>/topic.yml file or a named tile group from _data/home_topic_groups.yml.
assets/css/style.css Controls the shared visual styling.

What is front matter?

Front matter are fields used by Jekyll as metadata to control the visible content of the document on the page. Each Markdown file starts with front matter, and the exact fields depend on the page type. For the full list of fields and examples, see the Front Matter section.

The main idea

The site is organized around these topics, in menu order:

  1. Welcome
  2. Phase 1
  3. Phase 2
  4. New Features
  5. DCMS
  6. Database
  7. User Experience
  8. About

Each topic has:

  • a top-level menu item
  • a topic landing page
  • a shared tile bar
  • page descriptions for the linked documents

The top-level menu item links to its topic landing page and also opens its submenu. Every page in a topic uses the same header, breadcrumb and description bar, tile bar, and content layout.

Front matter fields

The most common fields are:

Field Purpose
layout Selects the page wrapper. Common options here are page, home, and redirect.
title The page title shown in the browser and on the page.
description Short description in the page banner.
permalink The public URL for the page.
nav_label Top-level menu label shown in the breadcrumb/title bar.
breadcrumb Full breadcrumb trail for the page banner.
topic_key Legacy topic identifier; the current tile include first selects topic data from _data/<topic>/topic.yml based on the page folder.
banner_tile_group Uses a non-topic tile group from _data/home_topic_groups.yml.
redirect_to Sends a redirect page to another URL.

What to edit for what purpose

Change a menu label, menu order, or top-level menu description

Edit:

  • _data/navigation.yml

This file controls the top-level menu labels and the basic descriptions associated with them.

Change the topic landing text, tile list, or document list

Edit:

  • Topic data files such as _data/database/topic.yml

Each topic data file is the source of truth for:

  • topic summaries
  • topic landing page document lists
  • topic tile text and destinations
  • page descriptions used in the topic tables

Redirects

Redirect pages use layout: redirect and a redirect_to value. The redirect layout sends visitors to the target page and keeps older links working after content moves.

Current redirect examples in this site:

The redirect behavior itself is defined in _layouts/redirect.html.

Change the header/menu behavior

Edit:

  • _includes/site-header.html

This file controls:

  • the logo
  • the top navigation
  • dropdown behavior
  • the contact button

Change the page title bar or breadcrumb-like label

Edit:

  • _includes/page-banner.html

This is where the menu/topic label and short description appear under the header.

Change the site-wide gate

Edit:

The gate is the overlay shown before access. The code is case-insensitive for ATPG.

Change the layout for topic pages or standard pages

Edit:

  • _layouts/home.html
  • _layouts/page.html
  • _layouts/default.html

These control the page wrappers. Both layouts use _includes/topic-tiles.html to render the correct tile bar before page content.

Change the site look and spacing

Edit:

This file controls:

  • logo size
  • menu spacing
  • dropdown width
  • page title bar spacing
  • tile widths
  • table styling
  • gate styling

Change the front matter rules or examples

The front matter guidance now lives in this page. Use the front matter section above when you need the common field definitions or the recommended minimal sets.

Folder structure

home/

The home section contains the landing page for the site.

dcms/

This folder contains the DCMS topic pages.

database/

This folder contains the database topic pages.

user-experience/

This folder contains shared experience pages and the patient and provider portal examples.

This folder contains the working documentation and maintenance guides for the site.

docs/

This folder contains older public documentation and archive-style supporting pages.

_data/

This folder stores the site’s structured data.

  • _data/navigation.yml controls the top menu
  • Topic data files such as _data/database/topic.yml control each topic’s summary, tiles, and page list

_includes/

Reusable pieces of the layout live here.

  • _includes/site-header.html
  • _includes/page-banner.html
  • _includes/site-gate.html

_layouts/

Page templates live here.

  • _layouts/default.html
  • _layouts/home.html
  • _layouts/page.html
  • _layouts/redirect.html

assets/

Shared styling and images live here.

The top-level menu item should do two things:

  1. act as a clickable link to the topic landing page
  2. open a dropdown with the related pages for that topic

That means the topic label is the navigation entry, and the dropdown is the menu list. The dropdown should not be the only way to reach the topic page.

Topic landing pages

When you click a topic such as Phase 1 or Phase 2, the landing page should show:

  • a short topic introduction
  • the list of pages in that topic
  • the topic tile bar, followed by the page content

The page title is a Markdown heading in the page content. The menu label comes from the navigation data.

Page descriptions

Page descriptions are what you see in the title bar next to the label. They should come from the page front matter when possible, or from the topic registry when the landing page is being generated.

Use the topic data file’s pages list to maintain the landing-page links and descriptions in one place.

Images, diagrams, and bitmaps

Images should be stored in a tracked asset folder such as assets/images/.

Use them from Markdown with normal image links or HTML:

![Database diagram](/assets/images/database-diagram.png)

For screenshots or SSMS diagrams, keep the image file separate and reference it from the page that needs it.

What to keep consistent

  • Keep menu labels short and stable.
  • Keep page descriptions brief.
  • Keep topic landing pages and the registry data in sync.
  • Keep dropdowns limited to the pages in that topic.
  • Keep the desktop layout readable, then simplify for mobile later.

Editing workflow

When adding a new page:

  1. Create the Markdown file in the topic folder.
  2. Add title, description, a topic breadcrumb, and a permalink in front matter.
  3. Add a Markdown # heading for the visible page title.
  4. Add the page to the topic’s pages list in _data/<topic>/topic.yml and to its submenu in _data/navigation.yml.
  5. Build and check the page from the topic landing page and the menu.

When changing a topic:

  1. Update the topic summary in _data/<topic>/topic.yml.
  2. Update the topic landing page content.
  3. Add or remove page links in the topic page list.
  4. Adjust tile text if the topic has tiles.

Notes

  • The guide can stay in docs/ as a helper page, but it is really a working reference.
  • If you want a private-only note later, it can move to a non-published location, but this version is usable as a site guide.
  • The goal is to keep the navigation, topic pages, and descriptions driven from the repo data instead of scattered through individual pages.

Back to top