Polish MkDocs site design

Author: Shashikant86

docs/index.md

@@ -1,4 +1,28 @@
-# CodexOpt
+<section class="codexopt-hero">
+  <h1>CodexOpt</h1>
+  <p class="codexopt-lead">
+    Benchmark and optimize <code>AGENTS.md</code> and <code>SKILL.md</code> for Codex with a repeatable developer workflow.
+  </p>
+  <p>
+    <a class="md-button md-button--primary" href="getting-started/">Get Started</a>
+    <a class="md-button" href="https://github.com/SuperagenticAI/codexopt-demo">View Demo Repo</a>
+  </p>
+</section>
+
+<div class="codexopt-grid">
+  <div class="codexopt-card">
+    <strong>Targeted</strong>
+    Focused on repo-local Codex assets: <code>AGENTS.md</code> and <code>SKILL.md</code>.
+  </div>
+  <div class="codexopt-card">
+    <strong>Measurable</strong>
+    Score instruction quality, attach evidence, and review artifact-backed changes.
+  </div>
+  <div class="codexopt-card">
+    <strong>Practical</strong>
+    Scan, benchmark, optimize, review, apply, and report from a single CLI.
+  </div>
+</div>
 
 CodexOpt helps teams benchmark and optimize Codex instruction assets with a repeatable workflow.
 
@@ -35,6 +59,18 @@ CodexOpt makes those problems measurable and easier to improve safely.
 - records artifacts under `.codexopt/`
 - generates markdown reports for review and PR discussion
 
+## Why Developers Use It
+
+Instruction files tend to drift long before teams notice:
+
+- duplicated rules
+- contradictory constraints
+- weak testing guidance
+- vague skill triggers
+- prompt bloat
+
+CodexOpt gives developers a way to improve those files with something closer to a normal engineering loop than ad hoc prompt editing.
+
 ## Demo Repository
 
 If you want a small example repo with intentionally messy instructions, use the companion demo:
@@ -51,4 +87,3 @@ uv run codexopt optimize agents --file AGENTS.md
 uv run codexopt optimize skills --glob ".codex/skills/**/SKILL.md"
 uv run codexopt report --output codexopt-report.md
 ```
-

docs/stylesheets/extra.css

@@ -0,0 +1,60 @@
+:root {
+  --md-primary-fg-color: #0f172a;
+  --md-primary-fg-color--light: #1e293b;
+  --md-primary-fg-color--dark: #020617;
+  --md-accent-fg-color: #0f766e;
+  --codexopt-hero-start: #eff6ff;
+  --codexopt-hero-end: #ecfeff;
+  --codexopt-card-border: rgba(15, 23, 42, 0.08);
+}
+
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color: #020617;
+  --md-primary-fg-color--light: #0f172a;
+  --md-primary-fg-color--dark: #000000;
+  --md-accent-fg-color: #5eead4;
+  --codexopt-hero-start: rgba(15, 23, 42, 0.92);
+  --codexopt-hero-end: rgba(8, 47, 73, 0.85);
+  --codexopt-card-border: rgba(148, 163, 184, 0.18);
+}
+
+.codexopt-hero {
+  padding: 2rem 1.25rem;
+  margin: 0 0 1.5rem 0;
+  border: 1px solid var(--codexopt-card-border);
+  border-radius: 1.25rem;
+  background: linear-gradient(135deg, var(--codexopt-hero-start), var(--codexopt-hero-end));
+}
+
+.codexopt-hero h1 {
+  margin-top: 0;
+  margin-bottom: 0.5rem;
+}
+
+.codexopt-lead {
+  font-size: 1.12rem;
+  max-width: 48rem;
+}
+
+.codexopt-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  gap: 0.9rem;
+  margin: 1.25rem 0 1.75rem 0;
+}
+
+.codexopt-card {
+  padding: 1rem;
+  border: 1px solid var(--codexopt-card-border);
+  border-radius: 1rem;
+  background: color-mix(in srgb, var(--md-default-bg-color) 92%, transparent);
+}
+
+.codexopt-card strong {
+  display: block;
+  margin-bottom: 0.35rem;
+}
+
+.md-typeset .md-button {
+  border-radius: 999px;
+}

mkdocs.yml

@@ -10,15 +10,37 @@ theme:
   logo: assets/codexopt_logo.png
   favicon: assets/codexopt_favicon.png
   features:
+    - navigation.instant
     - navigation.sections
     - navigation.top
+    - navigation.footer
     - content.code.copy
+    - content.action.edit
     - search.suggest
     - search.highlight
   palette:
     - scheme: default
-      primary: black
-      accent: blue
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - scheme: slate
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/SuperagenticAI/CodexOpt
+    - icon: material/play-box
+      link: https://github.com/SuperagenticAI/codexopt-demo
+
+extra_css:
+  - stylesheets/extra.css
 
 markdown_extensions:
   - admonition
@@ -31,6 +53,8 @@ markdown_extensions:
   - pymdownx.superfences
   - pymdownx.tabbed:
       alternate_style: true
+  - pymdownx.critic
+  - pymdownx.details
 
 nav:
   - Home: index.md
@@ -40,4 +64,3 @@ nav:
   - Optimization: optimization.md
   - Demo Repo: demo.md
   - FAQ: faq.md
-