Skip to content

DOCS.md

Latest commit

 

History

History
295 lines (223 loc) · 7.49 KB

DOCS.md

File metadata and controls

295 lines (223 loc) · 7.49 KB

Altar Documentation Editing Guide

This repository uses Jekyll for GitHub Pages, making it easy to edit and maintain documentation.

File Structure

Altar/
├── _config.yml           # Jekyll configuration
├── _data/                # Content data in YAML format (EDIT THESE!)
│   ├── index.yml         # Home page content
│   ├── sender.yml        # AltarSender page content
│   ├── docker.yml        # AltarDocker page content
│   └── extractor.yml     # AltarExtractor page content
├── _layouts/             # Page templates (rarely need editing)
│   ├── default.html      # Base layout
│   ├── home.html         # Home page layout
│   └── app.html          # App pages layout
├── assets/               # CSS and JavaScript
│   ├── styles.css        # Site styles
│   └── script.js         # Theme toggle and interactions
├── index.html            # Home page (just front matter)
├── sender.html           # AltarSender page (just front matter)
├── docker.html           # AltarDocker page (just front matter)
└── extractor.html        # AltarExtractor page (just front matter)

How to Edit Content

Editing Page Content

All page content is stored in YAML files in the _data/ folder. This makes editing easy without touching HTML:

Home Page (_data/index.yml)

meta:
  title: "Altar — Sacred experiment database tools"
  description: "Your description here"

hero:
  title: "Altar"
  subtitle: "Your subtitle with <strong>HTML</strong> support"
  primary_cta:
    text: "Get started"
    link: "#tools"
  secondary_cta:
    text: "View on GitHub"
    link: "https://github.com/DreamRepo"

tools:
  - icon: "fa-solid fa-cubes"
    title: "Tool Name"
    description: "Tool description"
    link: "page.html"
    linkText: "Learn more →"

features:
  - icon: "fa-solid fa-database"
    title: "Feature Name"
    description: "Feature description"

workflow:
  title: "How it works"
  steps:
    - title: "Step 1"
      description: "Step description"

App Pages (_data/sender.yml, docker.yml, extractor.yml)

meta:
  title: "Page Title"
  description: "Page description"

hero:
  icon: "fa-solid fa-icon-name"
  title: "App Name"
  subtitle: "App subtitle with <strong>HTML</strong>"
  primary_cta:
    text: "Button Text"
    link: "#features"
  secondary_cta:
    text: "View source"
    link: "https://github.com/..."

features:
  - icon: "fa-solid fa-icon"
    title: "Feature Name"
    description: "Feature description"

quick_start:
  - title: "Step Title"
    code: |
      # Multi-line code block
      command here
    content: "Additional text (optional)"

# Optional sections:
file_categories:      # For sender.yml
  - label: "Label"
    value: "Description"

default_urls:         # For docker.yml
  - label: "Service"
    value: "<code>URL</code>"

environment_vars:     # For extractor.yml
  - label: "VAR_NAME"
    value: "Description"

viewing_results:      # For sender.yml
  - label: "Type"
    value: "Location"

related_tools:
  - icon: "fa-solid fa-icon"
    title: "Tool Name"
    description: "Description"
    link: "page.html"

Editing Styles

Edit assets/styles.css to change colors, fonts, spacing, etc.

Editing Page Structure

Only edit layout files in _layouts/ if you need to change the structure:

Testing Locally

Prerequisites

# Install Ruby (required for Jekyll)
# On Windows: https://rubyinstaller.org/
# On macOS: brew install ruby
# On Linux: sudo apt-get install ruby-full

# Install Jekyll and Bundler
gem install jekyll bundler

Running Locally

# Navigate to the Altar directory
cd Altar

# Install dependencies (first time only)
bundle install

# Serve the site locally
bundle exec jekyll serve

# Open http://localhost:4000/Altar/ in your browser

Using Docker (Alternative)

# Run Jekyll in Docker
docker run --rm -v ${PWD}:/srv/jekyll -p 4000:4000 jekyll/jekyll:4.2.2 jekyll serve --watch --force_polling

Common Editing Tasks

Adding a New Feature

Edit the appropriate _data/*.yml file:

features:
  - icon: "fa-solid fa-star"  # Font Awesome icon
    title: "New Feature"
    description: "What this feature does"

Changing Button Links

hero:
  primary_cta:
    text: "New Text"
    link: "#new-section"  # Use #anchor or full URL

Adding Code Examples

quick_start:
  - title: "Installation"
    code: |
      pip install package
      python app.py
    content: "Additional explanation"

Updating Icons

Use Font Awesome 6 icons:

icon: "fa-solid fa-icon-name"

GitHub Pages Deployment

GitHub Pages automatically builds and deploys when you push to the main branch.

  • Site URL: https://dreamrepo.github.io/Altar/
  • Build time: Usually 1-3 minutes after push
  • View build status: Repository → Actions tab

Component READMEs (Monorepo)

App pages (AltarSender, AltarExtractor, AltarViewer, AltarDocker) embed their local README files from the component directories in this monorepo using a Jekyll include.

  • The page front matter sets:
    • readme_path: "AltarSender/README.md" (or the appropriate component path)
    • The layout includes submodule_readme.html, which renders that file in-place via include_relative
  • Component directories are excluded from direct publishing, but their README content is still rendered on the site.

No submodules are used anymore. Clone the repository normally:

git clone https://github.com/DreamRepo/Altar.git

Deployment Configuration

In _config.yml:

url: "https://dreamrepo.github.io"  # Your GitHub Pages domain
baseurl: "/Altar"                    # Repository name

Icons Reference

This site uses Font Awesome 6. Popular icons:

fa-solid fa-database      # Database
fa-solid fa-cloud         # Cloud
fa-solid fa-cubes         # Stack/Docker
fa-solid fa-paper-plane   # Send
fa-solid fa-chart-line    # Metrics
fa-solid fa-filter        # Filter
fa-solid fa-file-csv      # CSV
fa-solid fa-magnifying-glass-chart  # Search/Analysis

Troubleshooting

Site not updating after push?

  • Check GitHub Actions for build errors
  • Clear browser cache (Ctrl+Shift+R)
  • Wait 1-3 minutes for deployment

YAML syntax error?

Content not showing?

  • Verify the data_file matches the YAML filename
  • Check front matter in HTML files
  • Ensure YAML structure matches the layout

Resources

Tips

  1. Always test locally before pushing
  2. Use HTML in YAML for formatting: <strong>, <code>, <br>
  3. Keep YAML files tidy - proper indentation is crucial
  4. Font Awesome icons are free to use
  5. Commit small changes to track what works

Happy editing!

For questions or issues, see the main README or open an issue on GitHub.