feat: migrate to custom domain docs.specfact.io (#87)

* docs: improve documentation structure with unified command chains and cross-linking (#79)

Co-authored-by: Dominikus Nold <[email protected]>

* docs: add integrations overview guide (optional task 6.4)

- Create integrations-overview.md with comprehensive overview of all integrations
- Add links from integration guides to integrations-overview.md
- Add link to integrations-overview.md in docs/README.md
- Complete optional task 6.4 from improve-documentation-structure change

* docs: fix linting errors in integrations-overview.md

- Fix MD036 warnings by converting emphasis to proper headings
- Fix MD040 warning by adding language specifier to code block

* docs: simplify README and add links to new documentation

- Update website links to specfact.com / .io / .dev
- Add GitHub Pages docs link: https://nold-ai.github.io/specfact-cli/
- Remove version info section (avoids outdated info)
- Simplify content - remove verbose sections, add links to docs instead
- Add links to new documentation:
  - Command Chains Reference
  - Common Tasks Quick Reference
  - AI IDE Workflow Guide
  - Integrations Overview
- Improve onboarding with clear path for new users

* docs: add prominent SpecFact domain links with context

- Add specfact.com, specfact.io, specfact.dev links prominently at top
- Add domain purpose context (commercial, ecosystem, developer community)
- Highlight specfact.dev for developers
- Add GitHub Pages docs link
- Improve user navigation to appropriate resources

* docs: update Quick Start with correct IDE setup workflow

- Add Step 2: Initialize IDE integration (specfact init --ide)
- Update Step 3: Use slash commands in IDE or CLI
- Add realistic timing expectations (10-15 min for typical repos)
- Explain what init does (copies prompts, makes slash commands available)
- Add link to AI IDE Workflow Guide
- Remove unrealistic '60 seconds' claim

* fix: correct heading level for SpecFact Domains section

* docs: fix GitHub Pages permalinks for all documentation pages

- Update permalinks to include full directory path (e.g., /reference/commands/ instead of /commands/)
- Add frontmatter with permalinks to agile-scrum-workflows.md and reference/README.md
- Add frontmatter with permalink to speckit-journey.md for consistency
- All permalinks now match the Jekyll configuration pattern
- Enables proper GitHub Pages URLs for platform-frontend sites

* fix: resolve Jekyll build errors for GitHub Pages

- Quote title in speckit-journey.md frontmatter to fix YAML parsing error
- Wrap Jinja2 template code in {% raw %} tags in agile-scrum-workflows.md
  to prevent Jekyll from parsing it as Liquid syntax

Fixes GitHub Pages build errors:
- YAML Exception in speckit-journey.md (line 3)
- Liquid syntax error in agile-scrum-workflows.md (line 708)

* docs: add new pages to GitHub Pages navigation menu

- Add Command Chains to Guides section
- Add Agile/Scrum Workflows to Guides section
- Add Reference Documentation index to Reference section

These pages were missing from the navigation menu after fixing permalinks.

* docs: add new pages to GitHub Pages sidebar navigation menu

- Add Command Chains to Guides section (top of list)
- Add Agile/Scrum Workflows to Guides section
- Add Reference Documentation index to Reference section
- Fix reference links to use correct permalinks (/reference/architecture/, etc.)

The sidebar navigation menu is hardcoded in the layout file, so these
pages need to be manually added to appear in the left sidebar.

* feat: add Mermaid.js support for diagram rendering on GitHub Pages

- Add Mermaid.js CDN script to layout
- Add JavaScript to convert mermaid code blocks to renderable divs
- Handle kramdown output format (pre > code.language-mermaid)
- Initialize Mermaid with proper configuration

Fixes Mermaid diagram rendering on GitHub Pages documentation.
All mermaid code blocks will now render as interactive diagrams.

* feat: align GitHub Pages styling with specfact.io design

- Update color scheme to match specfact.io (dark theme with cyan accent)
- Change primary colors: #64ffda (cyan), #0a192f (dark blue), #112240 (light dark)
- Update Mermaid theme to dark with custom colors matching specfact.io
- Add Inter and JetBrains Mono fonts to match specfact.io typography
- Add Mermaid-specific CSS styling for better diagram appearance
- Remove light mode support, use dark theme consistently

Colors now match specfact.io:
- Primary/Highlight: #64ffda (cyan)
- Background: #0a192f (dark blue)
- Text: #ccd6f6 (light blue-gray)
- Code background: #1d2d50 (darker blue)

Mermaid diagrams now use dark theme with cyan accents for better
readability and visual consistency with specfact.io documentation site.

* fix: improve YAML and code syntax highlighting for dark theme

- Update Rouge syntax highlighting colors for dark theme readability
- Use cyan (#64ffda) for literals, numbers, and constants
- Use light green (#a8e6cf) for strings (better contrast on dark)
- Use pink (#ff6b9d) for keywords and operators
- Use purple (#c792ea) for functions and classes
- Use yellow (#ffd93d) for variables
- Use muted gray-blue (#8892b0) for comments
- YAML keys now use cyan color for better visibility

Fixes readability issues with YAML and other code blocks on dark background.

* feat: update to custom domain docs.specfact.io

- Update _config.yml: set baseurl to empty string for custom domain
- Update _config.yml: set url to https://docs.specfact.io
- Exclude assets/ from default permalink pattern to fix CSS path
- Update README.md to use new docs.specfact.io domain
- Fixes CSS 404 errors on custom domain

---------

Co-authored-by: Dominikus Nold <[email protected]>

Author: djm81

README.md

@@ -12,7 +12,7 @@
 
 <div align="center">
 
-**[🌐 specfact.com](https://specfact.com)** • **[📚 specfact.io](https://specfact.io)** • **[👨‍💻 specfact.dev](https://specfact.dev)** • **[📖 GitHub Pages Docs](https://nold-ai.github.io/specfact-cli/)** • **[💬 Support](mailto:[email protected])**
+**[🌐 specfact.com](https://specfact.com)** • **[📚 specfact.io](https://specfact.io)** • **[👨‍💻 specfact.dev](https://specfact.dev)** • **[📖 Documentation](https://docs.specfact.io/)** • **[💬 Support](mailto:[email protected])**
 
 </div>
 
@@ -21,7 +21,7 @@
 - **[specfact.com](https://specfact.com)** - Commercial landing page (marketing, pricing, enterprise)
 - **[specfact.io](https://specfact.io)** - Product ecosystem hub (CLI reference, integrations, changelog, product docs)
 - **[specfact.dev](https://specfact.dev)** - Developer community (tutorials, guides, blog, community content) ⭐ **For developers**
-- **[GitHub Pages Docs](https://nold-ai.github.io/specfact-cli/)** - Complete online documentation
+- **[docs.specfact.io](https://docs.specfact.io/)** - Complete online documentation
 
 ---
 
@@ -233,7 +233,7 @@ specfact import from-code my-project --repo .
 - **[DevOps Adapter Integration](docs/guides/devops-adapter-integration.md)** - GitHub Issues, Linear, Jira
 
 👉 **[Full Documentation Index](docs/README.md)** - Browse all documentation  
-👉 **[GitHub Pages Documentation](https://nold-ai.github.io/specfact-cli/)** - Online documentation site
+👉 **[Online Documentation](https://docs.specfact.io/)** - Complete documentation site
 
 ---
 

docs/_config.yml

@@ -4,8 +4,8 @@
 title: SpecFact CLI Documentation
 description: >-
   Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.
-baseurl: "/specfact-cli"  # Project pages require baseurl
-url: "https://nold-ai.github.io"  # GitHub Pages domain
+baseurl: ""  # Custom domain at root, no baseurl needed
+url: "https://docs.specfact.io"  # Custom domain
 
 # Build settings
 markdown: kramdown
@@ -36,7 +36,6 @@ exclude:
   - scripts
   - specs
   - resources
-  - "*.css.map"  # Exclude source map files
 
 # Source and destination (Jekyll will look for files in docs/)
 # Note: For GitHub Pages, Jekyll typically expects source in root or docs/
@@ -46,13 +45,21 @@ destination: _site
 
 # Defaults
 defaults:
-  # Apply permalink pattern only to markdown pages
-  # Note: Assets (SCSS files) are not pages, so they won't be affected by this
+  # Default layout for all pages
   - scope:
       path: ""
       type: pages
     values:
       layout: default
+  # Apply permalink pattern only to markdown files (exclude assets)
+  # Note: SCSS files with front matter are treated as pages and inherit this pattern
+  # We exclude assets/ directory to prevent CSS from being output at main/index.css
+  - scope:
+      path: ""
+      type: pages
+      exclude:
+        - "assets/**"
+    values:
       permalink: /:basename/
   - scope:
       path: "getting-started"
@@ -89,7 +96,7 @@ minima:
 # sass_dir is only needed for custom SASS partials directory
 sass:
   style: compressed
-  sourcemap: never  # Disable source maps to avoid conflicts
+  sourcemap: never  # Disable source maps to prevent JSON output
 
 # Footer
 footer:

docs/_layouts/default.html

@@ -5,6 +5,10 @@
     <meta http-equiv="X-UA-Compatible" content="IE=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     {% seo %}
+    <!-- Fonts -->
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
     <link rel="stylesheet" href="{{ '/assets/main.css' | relative_url }}">
     <link rel="alternate" type="application/rss+xml" title="{{ site.title | escape }}" href="{{ '/feed.xml' | relative_url }}">
     {% if jekyll.environment == 'production' and site.google_analytics %}
@@ -34,12 +38,61 @@
           }
         });
 
-        // Initialize Mermaid after converting all blocks
+        // Initialize Mermaid with dark theme matching specfact.io colors
         mermaid.initialize({ 
           startOnLoad: true,
-          theme: 'default',
+          theme: 'dark',
           securityLevel: 'loose',
-          flowchart: { useMaxWidth: true }
+          flowchart: { 
+            useMaxWidth: true,
+            htmlLabels: true,
+            curve: 'basis'
+          },
+          themeVariables: {
+            darkMode: true,
+            primaryColor: '#64ffda',
+            primaryTextColor: '#ccd6f6',
+            primaryBorderColor: '#64ffda',
+            lineColor: '#64ffda',
+            secondaryColor: '#112240',
+            tertiaryColor: '#1d2d50',
+            background: '#0a192f',
+            mainBkgColor: '#112240',
+            secondBkgColor: '#1d2d50',
+            textColor: '#ccd6f6',
+            border1: '#64ffda',
+            border2: '#8892b0',
+            noteBkgColor: '#1d2d50',
+            noteTextColor: '#ccd6f6',
+            noteBorderColor: '#64ffda',
+            actorBorder: '#64ffda',
+            actorBkg: '#112240',
+            actorTextColor: '#ccd6f6',
+            actorLineColor: '#64ffda',
+            labelBoxBkgColor: '#112240',
+            labelBoxBorderColor: '#64ffda',
+            labelTextColor: '#ccd6f6',
+            loopTextColor: '#ccd6f6',
+            activationBorderColor: '#64ffda',
+            activationBkgColor: '#1d2d50',
+            sequenceNumberColor: '#0a192f',
+            sectionBkgColor: '#1d2d50',
+            altBkgColor: '#112240',
+            critBkgColor: '#1d2d50',
+            doneBkgColor: '#64ffda',
+            doneBorderColor: '#64ffda',
+            taskBorderColor: '#64ffda',
+            taskBkgColor: '#112240',
+            taskTextLightColor: '#ccd6f6',
+            taskTextColor: '#ccd6f6',
+            taskTextDarkColor: '#0a192f',
+            taskTextOutsideColor: '#ccd6f6',
+            taskTextClickableColor: '#64ffda',
+            activeTaskBorderColor: '#64ffda',
+            activeTaskBkgColor: '#1d2d50',
+            gridColor: '#8892b0',
+            critBorderColor: '#64ffda'
+          }
         });
       });
     </script>