Avango Documentation

Quick Start Guide

This guide will help you get the Avango documentation site running locally using the new Jekyll + Primer CSS framework.

Prerequisites

Before you begin, make sure you have the following installed:

  1. Ruby (version 2.7 or higher)

    ruby --version

  2. Bundler

    gem install bundler

  3. Node.js (version 14 or higher)

    node --version

  4. Git

    git --version

Installation

# Clone the repository (if you haven't already)
git clone https://github.com/avango-tech/docs.avango.io.git
cd docs

# Run the bootstrap script (installs all dependencies)
./script/bootstrap

# Start the development server
./script/server

Option 2: Manual Installation

# Clone the repository
git clone https://github.com/avango-tech/docs.avango.io.git
cd docs

# Install Ruby dependencies
bundle install

# Install Node dependencies (Primer CSS)
npm install

# Start the development server with live reload
bundle exec jekyll serve --watch --livereload

Viewing the Site

Once the server is running, open your browser to:

http://localhost:4000

The site will automatically reload when you make changes to files.

Project Structure

docs/
├── _includes/              # Reusable components
│   ├── header.html        # Site header with navigation
│   └── footer.html        # Site footer
├── _layouts/              # Page templates
│   ├── home.html          # Homepage layout
│   └── support-page.html  # Documentation page layout
├── assets/
│   ├── css/
│   │   ├── style.scss     # Main stylesheet (imports Primer)
│   │   └── _custom.scss   # Custom Avango styles
│   └── img/               # Images and logos
├── api/                   # API documentation
├── script/                # Build and dev scripts
├── _config.yml            # Jekyll configuration
├── Gemfile                # Ruby dependencies
├── package.json           # Node dependencies
└── index.html             # Homepage content

Making Changes

Editing Content

  1. Homepage: Edit index.html
    • Uses Jekyll front matter and Liquid templates
    • Wrapped with the home layout
  2. Header/Footer: Edit _includes/header.html or _includes/footer.html
    • Changes apply to all pages
  3. Styles: Edit assets/css/_custom.scss
    • Custom styles on top of Primer CSS
    • Will be automatically compiled

Adding New Pages

Create a new file with Jekyll front matter:

---
layout: support-page
title: Your Page Title
description: Page description
---

<section class="container-lg p-responsive py-5">
  <h2 class="alt-h2">Your Content</h2>
  <p class="text-gray">Your content here...</p>
</section>

Using Primer CSS Classes

Layout & Grid

<div class="container-lg p-responsive">
  <!-- Responsive container -->
  <div class="col-md-6 float-left">
    <!-- 6-column grid -->
    <div class="clearfix gutter-spacious"><!-- Spaced grid --></div>
  </div>
</div>

Typography

<h1 class="alt-h1">Main heading</h1>
<h2 class="alt-h2">Section heading</h2>
<p class="alt-lead text-gray">Lead text</p>

Spacing

<div class="mb-3">
  <!-- Margin bottom -->
  <div class="py-5">
    <!-- Padding Y-axis -->
    <div class="mt-lg-6"><!-- Margin top (large screens) --></div>
  </div>
</div>

Buttons

<a href="#" class="btn btn-primary">Primary</a>
<a href="#" class="btn btn-outline">Outline</a>
<a href="#" class="btn btn-large">Large</a>

Colors

<div class="bg-gray-light">
  <!-- Background -->
  <p class="text-gray"><!-- Text color --></p>
  <p class="text-white"><!-- White text --></p>
</div>

Building for Production

# Build the site
./script/build

# Or manually
bundle exec jekyll build

The built site will be in the _site directory.

Deploying

The site automatically deploys to GitHub Pages when you push to the main branch.

git add .
git commit -m "Update documentation"
git push origin main

GitHub Actions will build and deploy automatically.

Troubleshooting

Port Already in Use

# Kill the process using port 4000
lsof -ti:4000 | xargs kill -9

# Or use a different port
bundle exec jekyll serve --port 4001

Bundle Install Errors

# Update bundler
gem install bundler

# Clean and reinstall
rm -rf .bundle vendor
bundle install

Node Modules Issues

# Clean and reinstall
rm -rf node_modules package-lock.json
npm install

Resources

Getting Help

Happy coding! 🚀