mrpiglr/AeThex-OS

Fork 0

mirror of https://github.com/AeThex-Corporation/AeThex-OS.git synced 2026-04-18 14:27:20 +00:00

MrPiglr 9cebf53f19

docs: Set up GitHub Pages organization

2026-01-06 00:23:40 +00:00

7.8 KiB

Raw Blame History

GitHub Pages Setup Guide

This document explains how to enable and use GitHub Pages for the AeThex OS documentation.

🚀 Quick Setup (5 Minutes)

Step 1: Enable GitHub Pages

Go to your repository: https://github.com/AeThex-Corporation/AeThex-OS
Click Settings (top right)
Scroll down to Pages (left sidebar)
Under Source, select:
- Source: GitHub Actions
- Branch: (not needed for Actions)
Click Save

Step 2: Push to Main Branch

The GitHub Actions workflow (.github/workflows/pages.yml) will automatically:

Build the Jekyll site
Deploy to GitHub Pages
Make it available at: https://aethex-corporation.github.io/AeThex-OS/

Step 3: Verify Deployment

Go to Actions tab in your repository
Watch the "Deploy GitHub Pages" workflow run

Once complete (green checkmark), visit your site:

https://aethex-corporation.github.io/AeThex-OS/

📁 Documentation Structure

AeThex-OS/
├── _config.yml                    # Jekyll configuration
├── README.md                      # Homepage (auto-displayed)
├── .github/workflows/pages.yml    # Deployment workflow
├── docs/
│   ├── index.md                   # Documentation hub
│   ├── AETHEX_OS_SPECIFICATION.md # ⭐ Core OS spec
│   ├── OAUTH_QUICKSTART.md
│   ├── OAUTH_SETUP.md
│   ├── OAUTH_IMPLEMENTATION.md
│   ├── CREDENTIALS_ROTATION.md
│   ├── ENTITLEMENTS_QUICKSTART.md
│   ├── PLATFORM_UI_GUIDE.md
│   ├── FLASH_USB.md
│   └── [redirect files].md        # URL-friendly slugs
└── [root markdown files].md        # Additional docs

🎨 Theme Customization

Current Theme: Cayman

The site uses the Cayman theme (dark header, clean design). To change:

Edit _config.yml:

theme: jekyll-theme-cayman

Available themes:

jekyll-theme-cayman (current)
jekyll-theme-slate (dark, code-focused)
jekyll-theme-architect (clean, professional)
minima (minimal, blog-style)
just-the-docs (documentation-focused, requires Gemfile)

Custom Styling

Create assets/css/style.scss:

---
---

@import "{{ site.theme }}";

/* Custom styles */
.main-content {
  max-width: 1200px;
}

📄 Adding New Documentation

Method 1: Direct Documentation (Preferred)

Add markdown files directly to docs/:

# Create new doc
echo "# My Feature\n\nContent here" > docs/MY_FEATURE.md

# Commit and push
git add docs/MY_FEATURE.md
git commit -m "docs: Add feature documentation"
git push

Will be available at: https://aethex-corporation.github.io/AeThex-OS/docs/MY_FEATURE

Method 2: URL-Friendly Redirects

For better URLs, create redirect files:

Create docs/my-feature.md:

---
layout: default
title: My Feature
permalink: /docs/my-feature
nav_order: 50
parent: Documentation
---

→ [View My Feature Documentation](MY_FEATURE)

Now accessible at: https://aethex-corporation.github.io/AeThex-OS/docs/my-feature

🔗 URL Structure

File	URL
`README.md`	`/AeThex-OS/` (homepage)
`docs/index.md`	`/AeThex-OS/docs/` (documentation hub)
`docs/AETHEX_OS_SPECIFICATION.md`	`/AeThex-OS/docs/AETHEX_OS_SPECIFICATION`
`docs/os-specification.md` (redirect)	`/AeThex-OS/docs/os-specification`
`LINUX_QUICKSTART.md`	`/AeThex-OS/LINUX_QUICKSTART`
`docs/linux-quickstart.md` (redirect)	`/AeThex-OS/docs/linux-quickstart`

🛠️ Local Testing

Option 1: Using Jekyll Locally

Install Jekyll:

# Ubuntu/Debian
sudo apt install ruby-full build-essential zlib1g-dev
gem install jekyll bundler

# macOS (via Homebrew)
brew install ruby
gem install jekyll bundler

Serve locally:

cd /workspaces/AeThex-OS
jekyll serve --baseurl "/AeThex-OS"

# Visit: http://localhost:4000/AeThex-OS/

Option 2: Using Docker

docker run --rm -v "$PWD":/usr/src/app -p 4000:4000 \
  starefossen/github-pages \
  jekyll serve --host 0.0.0.0 --baseurl "/AeThex-OS"

📊 Advanced Configuration

Custom Domain (Optional)

To use docs.aethex.com instead of GitHub Pages URL:

Create docs/CNAME file:
```
docs.aethex.com
```

Configure DNS:

CNAME docs -> aethex-corporation.github.io

Update _config.yml:

url: "https://docs.aethex.com"
baseurl: ""

Edit _config.yml:

navigation:
  - title: Home
    url: /
  - title: Documentation
    url: /docs/
  - title: OS Specification
    url: /docs/os-specification
  - title: GitHub
    url: https://github.com/AeThex-Corporation/AeThex-OS

Search (Requires Gemfile setup)

For just-the-docs theme:

Create Gemfile:

source "https://rubygems.org"
gem "github-pages", group: :jekyll_plugins
gem "just-the-docs"

Update _config.yml:

theme: just-the-docs
search_enabled: true

🎯 Best Practices

1. Keep OS Specification as Single Source of Truth

docs/AETHEX_OS_SPECIFICATION.md is the authoritative OS document
Link to it from other docs, don't duplicate content

2. Use Descriptive Filenames

✅ Good: OAUTH_QUICKSTART.md, ISO_BUILD_FIXED.md
❌ Avoid: doc1.md, temp.md

3. Organize by Topic

docs/
├── index.md              # Hub page
├── auth/                 # Authentication docs
├── build/                # Build guides
├── deployment/           # Deployment docs
└── reference/            # API references

4. Link Between Docs

Use relative links:

See the [OS Specification](AETHEX_OS_SPECIFICATION) for details.

5. Keep Front Matter Consistent

---
layout: default
title: Document Title
permalink: /docs/url-slug
nav_order: 10
parent: Documentation
---

🐛 Troubleshooting

Issue: "404 Not Found" after deployment

Solution: Check GitHub Actions logs:

Go to Actions tab
Click latest workflow run
Check for build errors

Issue: CSS not loading

Solution: Verify baseurl in _config.yml:

baseurl: "/AeThex-OS"  # Must match repo name

Issue: Links broken

Solution: Use absolute paths from root:

[Link](/AeThex-OS/docs/page)  # ✅ Correct
[Link](docs/page)              # ❌ May break

Issue: Workflow not running

Solution: Ensure workflow has permissions:

Settings → Actions → General
Set Workflow permissions to: "Read and write permissions"

📚 Resources

Jekyll Documentation: https://jekyllrb.com/docs/
GitHub Pages Docs: https://docs.github.com/pages
Supported Themes: https://pages.github.com/themes/
Jekyll Themes: http://jekyllthemes.org/

✅ Post-Setup Checklist

After enabling GitHub Pages:

Workflow runs successfully (green checkmark)
Site accessible at: https://aethex-corporation.github.io/AeThex-OS/
Homepage (README.md) displays correctly
Documentation index (/docs/) loads
OS Specification link works
OAuth guides accessible
All links navigate correctly
Update README.md with GitHub Pages URL
Announce documentation site to team

🚀 Next Steps

Review and test all documentation links
Add search functionality (requires theme upgrade)
Create API documentation (if needed)
Set up custom domain (optional)

Add Google Analytics (optional):

# _config.yml
google_analytics: UA-XXXXXXXX-X

Your documentation is now live at: 🌐 https://aethex-corporation.github.io/AeThex-OS/

Documentation Hub: 📚 https://aethex-corporation.github.io/AeThex-OS/docs/

OS Specification (Featured): ⭐ https://aethex-corporation.github.io/AeThex-OS/docs/os-specification

7.8 KiB Raw Blame History