Prexian

A Jekyll theme for open-source software and specification projects

Prexian is a powerful Jekyll theme designed to help organizations and individuals present open-source software and specifications in a navigable and elegant way. It supports both individual project sites and hub sites that aggregate multiple projects.

✨ Features

Two Site Types: Create individual project sites or hub sites that aggregate multiple projects
Smart Content Management: Automatically fetch and display software documentation, specifications, and project metadata from Git repositories
Performance Optimized: Intelligent caching system with shallow clones and sparse checkout
Modern Design: Clean, responsive design with customizable styling
SEO Ready: Built-in SEO optimization with jekyll-seo-tag integration
Blog Support: Full-featured blogging with author profiles and social links
Search Integration: Optional Algolia search support
AsciiDoc Support: First-class support for AsciiDoc content authoring

🚀 Quick Start

Installation

Add this line to your Jekyll site's Gemfile:

gem "prexian"

And then execute:

$ bundle install

Or install it yourself as:

$ gem install prexian

Basic Setup

Create a new Jekyll site:

jekyll new my-project-site
cd my-project-site

Add Prexian to your Gemfile:
```
gem "prexian"
```

Configure your site in _config.yml:

theme: prexian

plugins:
  - prexian

prexian:
  title: My Project
  description: An awesome open-source project
  tagline: Making the world a better place
  site_type: project  # or 'hub'

Build and serve:
```
bundle exec jekyll serve
```

📋 Minimum Requirements

Required Configuration

Every Prexian site must have these minimum configuration settings in _config.yml:

# Basic Jekyll configuration
title: Your Site Title
description: Your site description

# Theme configuration
theme: prexian
plugins:
  - prexian

# Prexian configuration (required)
prexian:
  site_type: project  # or 'hub' - REQUIRED
  title: Your Project Title
  description: Your project description

# Collections (required for content types you want to use)
collections:
  software:
    output: true
    permalink: /software/:path/
  specs:
    output: true
    permalink: /specs/:path/
  posts:
    output: true
    permalink: /blog/:year-:month-:day-:title/
  # For hub sites only:
  projects:
    output: false

# Defaults (required)
defaults:
  - scope:
      path: ""
    values:
      layout: default
  - scope:
      path: _posts
      type: posts
    values:
      layout: post
  - scope:
      path: _software
      type: software
    values:
      layout: product
  - scope:
      path: _specs
      type: specs
    values:
      layout: spec

Required Files

For All Sites

_config.yml - Site configuration (see above)

index.md - Homepage content:

---
layout: home
---

Your homepage content here...

For Project Sites

If your project site has a parent hub, add this to _config.yml:

prexian:
  hub:
    git_repo_url: https://github.com/your-org/hub-site
    git_repo_branch: main  # optional, defaults to 'main'
    home_url: https://your-hub-site.com/

For Hub Sites

assets/img/symbol.svg - Your site's logo (SVG format recommended) inserted at the footer
title.html - Your site's title (HTML format recommended) to be included in the footer

Without these two files the rendering of a project site will crash.

TODO: Fix this problem by detecting and skipping.

a _projects directory with project definitions:

# _projects/my-project.md
---
title: My Project
description: Brief project description
site:
  git_repo_url: https://github.com/your-org/my-project-site
  git_repo_branch: main
home_url: https://your-org.github.io/my-project/
---

Detailed project description...

Optional Files

Site Favicon

assets/favicon.png - Site favicon

Custom Styling

assets/css/style.scss - Custom styles:

---
---

...
@import "prexian";
@import "prexian/custom-styles";

// Your custom styles here

Content Pages

_pages/ - Static pages (about, contact, etc.)
_posts/ - Blog posts
_software/ - Software components
_specs/ - Specifications

Directory Structure Example

my-project-site/
├── _config.yml           # Required: Site configuration
├── index.md              # Required: Homepage
├── Gemfile               # Required: Dependencies
├── title.html            # Required (for hub): Title file
├── assets/
│   ├── symbol.svg        # Required (for hub): Site logo
│   └── css/
│       └── style.scss    # Optional: Custom styles
├── _pages/               # Optional: Static pages
│   ├── about.md
│   └── contact.md
├── _posts/               # Optional: Blog posts
│   └── 2024-01-01-welcome.md
├── _software/            # Optional: Software components
│   └── my-tool.md
└── _specs/               # Optional: Specifications
    └── my-spec.md

This is the absolute minimum needed to get a Prexian site running. You can then add content and customize as needed.

📖 Site Types

Prexian supports two distinct types of sites, each with specific purposes and capabilities:

Project Site

A project site describes one individual project and can contain:

Software components: Individual software products with their documentation
Specifications: Technical specifications and standards
Blog posts: Project-specific announcements and articles
Documentation: Project-wide documentation and guides
Pages: Static pages for additional content

Project sites are designed to be comprehensive resources for a single project, providing everything users need to understand, use, and contribute to the project.

# _config.yml for project site
prexian:
  site_type: project
  hub:
    git_repo_url: https://github.com/your-org/hub-site
    git_repo_branch: main
    home_url: https://your-org.github.io/

Hub Site

A hub site aggregates multiple project sites into a unified portal. Hub sites can contain:

Projects collection: Links to individual project sites
Aggregated software: Software from all projects in the hub
Aggregated specifications: Specifications from all projects
Hub-wide blog: Organization-level announcements and articles
All project site components: Hub sites can also have their own software, specs, and content

Hub sites serve as the central entry point for organizations with multiple related projects, providing a unified view of all activities and resources.

# _config.yml for hub site
prexian:
  site_type: hub

collections:
  projects:
    output: false

🏗️ Building Project and Hub Sites

Adding Projects (Hub Sites Only)

Projects are defined in the _projects collection. Each project points to a separate Prexian project site:

# _projects/my-project.md
---
title: My Awesome Project
description: A sentence or two about what the project is for.
tagline: Because awesomeness is underrated
featured: true  # Include in featured projects on hub home page

site:
  git_repo_url: https://github.com/your-org/my-project-site
  git_repo_branch: main

home_url: https://your-org.github.io/my-project/
tags: [awesome, project, open-source]
---

Detailed description of the project goes here...

Adding Software

Software components are defined in the _software collection:

# _software/my-tool.md
---
title: My Development Tool
description: A powerful tool for developers
repo_url: https://github.com/your-org/my-tool
repo_branch: main  # Optional, defaults to site's default_repo_branch

# Optional: Separate documentation repository
docs:
  git_repo_url: https://github.com/your-org/my-tool-docs
  git_repo_subtree: docs
  git_repo_branch: main

tags: [Ruby, CLI, Developer Tools]
external_links:
  - url: https://github.com/your-org/my-tool
  - url: https://rubydoc.info/gems/my-tool
    title: "API Documentation"

feature_with_priority: 1  # Featured on home page
---

Your software description goes here...

Software Logo: Place an SVG logo at _software/my-tool/assets/img/symbol.svg

Adding Specifications

Specifications are defined in the _specs collection:

# _specs/my-spec.md
---
title: My Technical Specification
description: A comprehensive specification for X protocol
tags: [RFC, Standard, Protocol]

external_links:
  - url: https://tools.ietf.org/html/rfc1234
    title: "RFC 1234"

# Optional: Build specification from source
spec_source:
  git_repo_url: https://github.com/your-org/spec-repo
  git_repo_subtree: specification
  git_repo_branch: main
  build:
    engine: png_diagram_page
    options:
      format: png

# Optional: Custom navigation for built specs
navigation:
  sections:
    - name: "Diagrams"
      items:
        - title: "Overview Diagram"
          path: "overview"
          description: "System overview"
---

Your specification description goes here...

Adding Custom Content Types (e.g., Advisories)

You can extend Prexian with custom collections:

Define the collection in _config.yml:

collections:
  advisories:
    output: true
    permalink: /advisories/:path/

defaults:
  - scope:
      path: _advisories
      type: advisories
    values:
      layout: advisory  # Create this layout

Create content in _advisories/:

# _advisories/security-advisory-001.md
---
title: Security Advisory 001
severity: high
date: 2024-01-15
affected_versions: ["< 2.1.0"]
tags: [security, vulnerability]
---

Description of the security issue...

Create an index page in _pages/advisories.html:

---
title: Security Advisories
layout: advisory-index  # Create this layout
hero_include: index-page-hero.html
---

Hero Sections and Custom Introductions

Adding a Hero Section

Add a hero section to any page by specifying hero_include in the frontmatter:

---
title: My Page
hero_include: index-page-hero.html
---

Custom Introduction Section

For project sites, you can add a custom introduction section:

Enable it in _config.yml:

prexian:
  landing_priority:
    - custom_intro
    - software
    - specs
    - blog

Create the include file custom-intro.html:

<section class="custom-intro">
  <div class="summary">
    <h2>Welcome to {{ site.title }}</h2>
    <p>{{ site.description }}</p>
  </div>

  <div class="call-to-action">
    <a href="/getting-started" class="btn btn-primary">Get Started</a>
    <a href="/documentation" class="btn btn-secondary">Documentation</a>
  </div>
</section>

Tag Namespaces

Tag namespaces help organize and categorize content with semantic meaning:

# _config.yml
tag_namespaces:
  software:
    writtenin: "Written in"        # Programming languages
    bindingsfor: "Bindings for"    # Language bindings
    user: "Target user"            # Target audience
    interface: "Interface"         # UI type (CLI, GUI, API)
  specs:
    audience: "Audience"           # Who the spec is for
    completion_status: "Status"    # Draft, Final, etc.
    domain: "Domain"               # Technical domain

Use namespaced tags in your content:

tags: [writtenin:Ruby, user:Developer, interface:CLI, audience:Technical]

Collections Configuration

Collections define the types of content your site can contain:

# _config.yml
collections:
  # Core Prexian collections
  software:
    output: true
    permalink: /software/:path/
  specs:
    output: true
    permalink: /specs/:path/
  posts:
    output: true
    permalink: /blog/:year-:month-:day-:title/

  # Hub sites only
  projects:
    output: false

  # Custom collections
  advisories:
    output: true
    permalink: /advisories/:path/
  tutorials:
    output: true
    permalink: /tutorials/:path/

Data Collections

Prexian supports Jekyll's data collections for structured content. Create YAML files in _data/:

# _data/team.yml
- name: John Doe
  role: Lead Developer
  github: johndoe

- name: Jane Smith
  role: Technical Writer
  github: janesmith

Use in templates:

{% for member in site.data.team %}
  <div class="team-member">
    <h3>{{ member.name }}</h3>
    <p>{{ member.role }}</p>
  </div>
{% endfor %}

🔧 Configuration

Essential Configuration

# _config.yml
title: Your Project Name
description: A brief description of your project
url: https://your-project.github.io

prexian:
  title: Your Project Name
  description: A brief description of your project
  tagline: Your project's tagline
  site_type: project  # 'project' or 'hub'

  author: "Your Organization"
  authors:
    - name: Your Name
      email: [email protected]

  social:
    links:
      - https://github.com/your-org
      - https://twitter.com/your-org

  github_repo_url: https://github.com/your-org/your-project
  default_repo_branch: main  # Default branch for all repositories

Git Repository Configuration

All Git repository references support branch/version specification:

# For parent hub
prexian:
  hub:
    git_repo_url: https://github.com/your-org/hub-site
    git_repo_branch: main  # or version tag like 'v1.2.3'

# For software documentation
# _software/my-tool.md
docs:
  git_repo_url: https://github.com/your-org/my-tool-docs
  git_repo_branch: main  # or 'develop', 'v2.0', etc.

# For specifications
# _specs/my-spec.md
spec_source:
  git_repo_url: https://github.com/your-org/spec-repo
  git_repo_branch: main  # or 'draft', 'v1.0', etc.

🏗️ Internal Architecture

Developer Services

Prexian provides several internal services for developers:

`Prexian::Configuration`

Centralized configuration management with validation:

config = Prexian::Configuration.new(site.config)
config.site_type        # => 'project' or 'hub'
config.hub_site?        # => true/false
config.default_repo_branch  # => 'main'

`Prexian::GitService`

Repository operations with caching:

git_service = Prexian::GitService.new
result = git_service.shallow_checkout(repo_url, branch: 'main')
git_service.copy_cached_content(result[:local_path], destination)

`Prexian::HubSiteLoader`

Aggregates content from multiple project repositories for hub sites.

`Prexian::ProjectSiteLoader`

Handles individual project site content and parent hub integration.

The `_hub-site` Directory

For project sites with a parent hub, Prexian automatically:

Fetches hub content from the parent hub repository
Copies it to _hub-site/hub/ in your project site
Adds it to include paths so you can reference hub assets

This allows project sites to:

Use the hub's logo: {% include hub/assets/img/symbol.svg %}
Reference hub branding: {% include hub/title.html %}
Maintain consistent styling with the hub

The _hub-site directory structure:

_hub-site/
└── hub/
    ├── assets/
    │   └── symbol.svg
    ├── title.html
    └── other-hub-includes.html

🎨 Customization

Styling

Create custom styles in assets/css/style.scss:

---
---

@import "prexian/custom-variables";
@import "prexian";
@import "prexian/custom-styles";

// Your custom styles here
.custom-class {
  color: #your-color;
}

Layouts and Includes

Override theme layouts by creating files in _layouts/ and includes in your site root (not _includes/):

title.html - Custom site title/logo
custom-intro.html - Custom introduction section
project-nav.html - Additional navigation links

Logo and Symbol Guidelines

Site Symbol

Format: SVG
Size: Should look good at 30x30px and 60x60px
Location: assets/img/symbol.svg
Requirements:
- No IDs in SVG markup (appears multiple times on page)
- Root <svg> element must have viewBox attribute
- No width or height attributes on root element

Favicon

Provide PNG renders as:

assets/favicon.png
assets/favicon-192x192.png

Use transparent background for PNG files.

🔧 CLI Tools

Prexian includes command-line tools for cache management:

# Check version
bundle exec prexian version

# Clear cache
bundle exec prexian cache clear

# Show cache status
bundle exec prexian cache status

🐛 Debugging and Troubleshooting

Building this site itself

The Prexian site itself is a project site of the ribose.com hub site.

./script/build
./script/test
./script/server

Testing Site Builds

Use the provided test scripts to verify your site works correctly:

Test Hub Sites

# Test hub site functionality
./script/test-hub

# Build hub site for production
./script/build-hub

# Verify these elements are present:
# - Project software components from all projects
# - Project specifications from all projects
# - Project blog posts alongside hub posts
# - Proper navigation and layout

Test Project Sites

# Test project site functionality
./script/test-project

# Build project site for production
./script/build-project

# Verify these elements are present:
# - Parent hub logo/link in footer
# - Proper /specs/ page layout and content
# - All project-specific content (software, specs, blog)
# - Consistent styling with parent hub

Common Debugging Steps

1. Check Configuration

Ensure your _config.yml has the required settings:

# For project sites
prexian:
  site_type: project
  hub:
    git_repo_url: https://github.com/your-org/hub-site
    git_repo_branch: main
    home_url: https://your-hub-site.com/

# For hub sites
prexian:
  site_type: hub

collections:
  projects:
    output: false

2. Verify Repository Access

Check that all Git repositories are accessible:

# Test hub repository access (for project sites)
git ls-remote https://github.com/your-org/hub-site

# Test project repository access (for hub sites)
git ls-remote https://github.com/your-org/project-site

3. Clear Cache

If you're seeing stale content:

bundle exec prexian cache clear
bundle exec jekyll clean

4. Check Build Output

Look for error messages during build:

bundle exec jekyll build --verbose

5. Inspect Generated Files

Check that content is being loaded correctly:

# For project sites, verify hub content is loaded
ls -la _hub-site/hub/

# For hub sites, verify project content is loaded
ls -la _project-sites/

Common Issues and Solutions

Hub Sites Not Showing Project Content

Symptoms: Hub site builds successfully but doesn't display software, specifications, or blog posts from projects.

Check:

Verify project definitions in _projects/ directory
Ensure project repositories are accessible
Check that project sites have the correct site_type: project configuration
Clear cache and rebuild: bundle exec prexian cache clear && bundle exec jekyll build

Project Sites Missing Hub Assets

Symptoms: Project site builds but missing parent hub logo, branding, or styling.

Check:

Verify hub configuration in _config.yml
Ensure hub repository is accessible
Check that hub site has the correct site_type: hub configuration
Verify _hub-site/hub/ directory is created during build

Broken `/specs/` Page Layout

Symptoms: Specifications page loads but has incorrect styling or missing content.

Check:

Verify specifications are defined in _specs/ collection
Check that specs collection is configured in _config.yml
Ensure specification files have correct frontmatter
Verify spec-index layout is available

Path Configuration

All paths for software, specifications, and projects should use relative paths from the repository root, not absolute filesystem paths.

Correct:

# _software/my-tool.md
docs:
  git_repo_url: https://github.com/your-org/my-tool
  git_repo_subtree: docs  # Relative path within the repository

# _specs/my-spec.md
spec_source:
  git_repo_url: https://github.com/your-org/spec-repo
  git_repo_subtree: specification  # Relative path within the repository

Incorrect:

# Don't use absolute paths
docs:
  git_repo_subtree: /Users/username/projects/docs  # ❌ Absolute path

Performance Tips

Use git_repo_branch to pin to specific versions for stability
Use shallow clones (automatic) for faster builds
Clear cache periodically: bundle exec prexian cache clear
Use bundle exec jekyll serve --incremental for faster development builds

Development Workflow

When developing themes or debugging issues:

Use test scripts: ./script/test-hub or ./script/test-project
Check logs: Look for error messages in Jekyll build output
Inspect generated files: Verify content is loaded in _hub-site/ or _project-sites/
Clear cache: Use bundle exec prexian cache clear when switching between configurations
Test incrementally: Make small changes and test frequently

🛠️ Theme Development

Building the Theme

When developing the Prexian theme itself, you cannot use the standard _config.yml file because it gets inherited by user gems. Instead, use one of these methods:

Method 1: Use the Theme Development Configuration

# Build with theme development config
bundle exec jekyll build --config _config_theme-dev.yml

# Serve with theme development config
bundle exec jekyll serve --config _config_theme-dev.yml

Method 2: Use the Build Script

# Build the example site
script/build

# Serve the example site
script/server

The _config_theme-dev.yml file contains the proper configuration for testing the theme with example content, while _config.yml is kept minimal for gem users.

Configuration Files

_config.yml: Minimal configuration inherited by gem users
_config_theme-dev.yml: Full development configuration with example content
script/build: Convenience script that uses the theme development config
script/server: Development server script

Testing Changes

After making changes to the theme:

Test the build:
```
script/build
```

Test the CLI tools:

bundle exec prexian version
bundle exec prexian cache status

Run the test suite:
```
bundle exec rspec
```
Serve locally to verify:
```
script/server
```

📝 Content Authoring

AsciiDoc Support

Content is expected to be authored in AsciiDoc for full feature support:

---
title: My Documentation Page
layout: docs-base
---
:page-liquid:

= My Documentation

== Introduction

This is an AsciiDoc document with full Prexian support.

[source,ruby]
----
puts "Hello, World!"
----

Disabling Copy Buttons

By default, code listings have copy buttons. To disable for a specific listing:

[.nocopy]
[source,sh]
----
some command
----

Blog Posts

---
layout: post
title: "Announcing Version 2.0"
date: 2024-01-15
authors:
  - name: John Doe
    email: [email protected]
    use_picture: gravatar  # 'gravatar', 'assets', 'no', or path
    social_links:
      - https://github.com/johndoe
      - https://twitter.com/johndoe
excerpt: >-
  We're excited to announce the release of version 2.0 with many new features.
card_image: /assets/blog/v2-announcement.png  # Optional cover image
---

Your blog post content goes here...

🔄 Migration from jekyll-theme-open-project

If you're migrating from the old jekyll-theme-open-project:

Update Gemfile:

# Remove old gems
# gem "jekyll-theme-open-project"
# gem "jekyll-theme-open-project-helpers"

# Add new gem
gem "prexian"

Update _config.yml:

# Remove old plugins
plugins:
  - prexian  # Replace all old plugins with this

# Update site type configuration
prexian:
  site_type: hub  # instead of is_hub: true

Update SCSS imports:

// Old
@import 'jekyll-theme-open-project';

// New
@import 'prexian';

Update engine references:

# Old
engine: png_diagrams

# New
engine: png_diagram_page

Make sure you have required files:
- assets/img/symbol.svg
- title.html

🌟 Examples

See Prexian in action:

Metanorma - Standards authoring platform
RNP - OpenPGP implementation
Relaton - Bibliographic data toolkit

🤝 Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/riboseinc/prexian.

📄 License

The theme is available as open source under the terms of the MIT License.

🆘 Support

Documentation: Full documentation available in this README
Issues: Report bugs and request features on GitHub Issues
Discussions: Join the conversation on GitHub Discussions

Detailed Configuration Reference

Click to expand complete configuration options

Complete Configuration Example

# _config.yml
title: Your Project
description: Project description
url: https://your-project.github.io

prexian:
  title: Your Project
  description: Project description
  tagline: Your project tagline

  # Site type (required)
  site_type: project  # 'project' or 'hub'

  # Repository settings
  default_repo_branch: main
  github_repo_url: https://github.com/your-org/your-project
  github_repo_branch: main

  # Author information
  author: "Your Organization"
  authors:
    - name: Your Name
      email: [email protected]
  contact_email: [email protected]

  # Parent hub (for project sites)
  hub:
    git_repo_url: https://github.com/your-org/hub-site
    git_repo_branch: main
    home_url: https://your-org.github.io/

  # Social links
  social:
    links:
      - https://github.com/your-org
      - https://twitter.com/your-org

  # Legal information
  legal:
    name: Your Organization
    tos_link: https://your-org.com/terms
    privacy_policy_link: https://your-org.com/privacy

  # Search (optional)
  algolia_search:
    api_key: 'your-api-key'
    index_name: 'your-index'

  # Landing page sections order
  landing_priority:
    - software
    - specs
    - blog
    - custom_intro

  # Call-to-action buttons
  home_calls_to_action:
    - url: "/getting-started"
      title: "Get Started"
    - url: "/documentation"
      title: "Documentation"

# Tag namespaces
tag_namespaces:
  software:
    writtenin: "Written in"
    user: "Target user"
    interface: "Interface"
  specs:
    audience: "Audience"
    completion_status: "Status"

# Jekyll collections (required)
collections:
  projects:    # Only for hub sites
    output: false
  software:
    output: true
    permalink: /software/:path/
  specs:
    output: true
    permalink: /specs/:path/
  posts:
    output: true
    permalink: /blog/:year-:month-:day-:title/
  pages:
    output: true
    permalink: /:name/

# Jekyll defaults (required)
defaults:
  - scope:
      path: ""
    values:
      layout: default
  - scope:
      path: _posts
      type: posts
    values:
      layout: post
  - scope:
      path: _software
      type: software
    values:
      layout: product
  - scope:
      path: _specs
      type: specs
    values:
      layout: spec

# Plugins
plugins:
  - prexian

# Exclude files
exclude:
  - .git
  - Gemfile*
  - README.*
  - vendor
  - script

Theme Layouts

Available layouts:

default: Main layout with html-class support
home: Homepage layout
post: Blog post layout
product: Software product layout
spec: Specification layout
blog-index: Blog index page
software-index: Software index page (hub sites)
spec-index: Specification index page (hub sites)
project-index: Project index page (hub sites)
docs-base: Documentation base layout
page: Generic page layout

Theme Includes

Commonly overridden includes:

title.html: Site name/logo
custom-intro.html: Custom introduction section
project-nav.html: Additional navigation links
assets/img/symbol.svg: Site symbol
head.html: Custom head content
scripts.html: Custom JavaScript

Content Guidelines

Project/Software/Spec titles: 1-3 words, title case
Descriptions: ~12 words, no markup
Featured descriptions: ~20-24 words, no markup
Blog post titles: 3-7 words
Blog post excerpts: ~20-24 words, no markup
Taglines: Short, memorable phrases

Name		Name	Last commit message	Last commit date
Latest commit History 752 Commits
.github/workflows		.github/workflows
_data		_data
_includes		_includes
_layouts		_layouts
_pages		_pages
_posts		_posts
_sass		_sass
assets		assets
develop		develop
exe		exe
lib		lib
script		script
spec		spec
.gitignore		.gitignore
.rspec		.rspec
.rubocop.yml		.rubocop.yml
.rubocop_todo.yml		.rubocop_todo.yml
CHANGELOG.adoc		CHANGELOG.adoc
CI_OPS.md		CI_OPS.md
Gemfile		Gemfile
LICENSE.txt		LICENSE.txt
README.md		README.md
Rakefile		Rakefile
_config.yml		_config.yml
_config_prexian.yml		_config_prexian.yml
index.md		index.md
prexian.gemspec		prexian.gemspec

License

riboseinc/prexian

Folders and files

Latest commit

History

Repository files navigation

Prexian

✨ Features

🚀 Quick Start

Installation

Basic Setup

📋 Minimum Requirements

Required Configuration

Required Files

For All Sites

For Project Sites

For Hub Sites

Optional Files

Site Favicon

Custom Styling

Content Pages

Directory Structure Example

📖 Site Types

Project Site

Hub Site

🏗️ Building Project and Hub Sites

Adding Projects (Hub Sites Only)

Adding Software

Adding Specifications

Adding Custom Content Types (e.g., Advisories)

Hero Sections and Custom Introductions

Adding a Hero Section

Custom Introduction Section

Tag Namespaces

Collections Configuration

Data Collections

🔧 Configuration

Essential Configuration

Git Repository Configuration

🏗️ Internal Architecture

Developer Services

Prexian::Configuration

Prexian::GitService

Prexian::HubSiteLoader

Prexian::ProjectSiteLoader

The _hub-site Directory

🎨 Customization

Styling

Layouts and Includes

Logo and Symbol Guidelines

Site Symbol

Favicon

🔧 CLI Tools

🐛 Debugging and Troubleshooting

Building this site itself

Testing Site Builds

Test Hub Sites

Test Project Sites

Common Debugging Steps

1. Check Configuration

2. Verify Repository Access

3. Clear Cache

4. Check Build Output

5. Inspect Generated Files

Common Issues and Solutions

Hub Sites Not Showing Project Content

Project Sites Missing Hub Assets

Broken /specs/ Page Layout

Path Configuration

Performance Tips

Development Workflow

🛠️ Theme Development

Building the Theme

Method 1: Use the Theme Development Configuration

Method 2: Use the Build Script

Configuration Files

Testing Changes

📝 Content Authoring

AsciiDoc Support

Disabling Copy Buttons

`Prexian::Configuration`

`Prexian::GitService`

`Prexian::HubSiteLoader`

`Prexian::ProjectSiteLoader`

The `_hub-site` Directory

Broken `/specs/` Page Layout

Packages