Feat/refactor 1

.github/workflows/build.yml

@@ -77,6 +77,14 @@ jobs:
         echo "HUGO_VERSION=$VERSION" >> $GITHUB_ENV
         echo "Using Hugo version: $VERSION"
 
+    - name: Checkout twinkle docs
+      uses: actions/checkout@v4
+      with:
+        repository: modelscope/twinkle
+        path: twinkle
+        sparse-checkout: docs/
+        sparse-checkout-cone-mode: true
+
     - name: Install dependencies
       run: |
         # Install Tailwind CLI if package.json exists
@@ -112,6 +120,14 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-hugo-resources-
 
+    - name: Sync docs from twinkle repo
+      env:
+        TWINKLE_DOCS_DIR: ${{ github.workspace }}/twinkle/docs
+      run: python3 scripts/sync-docs.py
+
+    - name: Check internal links
+      run: python3 scripts/check-links.py
+
     - name: Build with Hugo
       env:
         HUGO_ENVIRONMENT: production

.gitignore

@@ -45,6 +45,10 @@ node_modules/
 pagefind/
 static/pagefind/
 
+# Auto-generated docs (by scripts/sync-docs.py from docs/source_en & docs/source_zh)
+content/docs/components/
+content/docs/usage-guide/
+
 # ============================================================================
 # Operating System
 # ============================================================================

assets/css/custom.css

@@ -463,6 +463,40 @@ header,
   color: var(--twinkle-primary) !important;
 }
 
+/* Force horizontal navbar at md breakpoint (768px) instead of lg (1024px) */
+@media (min-width: 768px) {
+  /* Hide hamburger button */
+  label[for="nav-toggle"] {
+    display: none !important;
+  }
+  /* Show nav menu horizontally */
+  #nav-menu {
+    display: flex !important;
+    width: auto !important;
+    padding-bottom: 0 !important;
+    gap: 0.25rem;
+  }
+  .navbar-nav {
+    text-align: left;
+  }
+  .nav-link {
+    padding: 0.5rem 0.6rem;
+    font-size: 0.9rem;
+  }
+}
+
+/* Show docs sidebar at md breakpoint (768px) instead of lg (1024px) */
+@media (min-width: 768px) and (max-width: 1023px) {
+  .hb-sidebar-container {
+    position: sticky !important;
+    top: 4rem !important;
+    transform: none !important;
+    width: 16rem !important;
+    flex-shrink: 0 !important;
+    align-self: flex-start !important;
+  }
+}
+
 /* ─────────────────────────────────────────────────────────────────────────────
    Footer - Light
    ───────────────────────────────────────────────────────────────────────────── */
@@ -551,3 +585,134 @@ footer {
   background: #0f172a !important;
   border-color: #334155;
 }
+
+/* ─────────────────────────────────────────────────────────────────────────────
+   Cookbook (Showcase) - Two-Column Card Grid
+   ───────────────────────────────────────────────────────────────────────────── */
+.page-body .container.grid {
+  max-width: 72rem !important;
+  grid-template-columns: 1fr !important;
+}
+
+@media (min-width: 768px) {
+  .page-body .container.grid {
+    grid-template-columns: repeat(2, 1fr) !important;
+  }
+}
+
+/* Compact card image area */
+.page-body .container.grid .aspect-\[16\/9\] {
+  aspect-ratio: 16/10 !important;
+}
+
+/* Reduce card padding for compactness */
+.page-body .container.grid .p-8 {
+  padding: 1.25rem !important;
+}
+
+.page-body .container.grid .space-y-4 {
+  gap: 0.5rem !important;
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+   Stats Block: force 2×2 grid instead of 4-column to prevent text truncation
+   ───────────────────────────────────────────────────────────────────────────── */
+.blox-stats .grid {
+  grid-template-columns: repeat(2, minmax(0, 1fr)) !important;
+}
+
+.blox-stats .grid h3 {
+  font-size: clamp(1.5rem, 4vw, 2.5rem) !important;
+  white-space: nowrap;
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+   Language Switcher
+   ───────────────────────────────────────────────────────────────────────────── */
+.lang-switcher {
+  display: inline-flex;
+  align-items: center;
+  background: var(--twinkle-surface-alt);
+  border-radius: 6px;
+  padding: 2px;
+  gap: 2px;
+  font-size: 0.8rem;
+  font-weight: 500;
+}
+
+.lang-switcher-active {
+  padding: 0.25rem 0.6rem;
+  border-radius: 4px;
+  background: var(--twinkle-primary);
+  color: white;
+}
+
+.lang-switcher-link {
+  padding: 0.25rem 0.6rem;
+  border-radius: 4px;
+  text-decoration: none;
+  color: var(--twinkle-text-secondary);
+  transition: background 0.15s;
+}
+
+.lang-switcher-link:hover {
+  background: var(--twinkle-border);
+}
+
+.dark .lang-switcher {
+  background: #334155;
+}
+
+.dark .lang-switcher-link {
+  color: #cbd5e1;
+}
+
+.dark .lang-switcher-link:hover {
+  background: #475569;
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+   List Children Shortcode
+   ───────────────────────────────────────────────────────────────────────────── */
+.list-children-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
+  gap: 1rem;
+  margin-top: 1.5rem;
+}
+
+.list-children-card {
+  display: flex;
+  flex-direction: column;
+  padding: 1rem 1.25rem;
+  border: 1px solid var(--twinkle-border);
+  border-radius: 0.5rem;
+  text-decoration: none;
+  color: inherit;
+  transition: box-shadow 0.2s, border-color 0.2s;
+}
+
+.list-children-card:hover {
+  border-color: var(--twinkle-primary);
+  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+}
+
+.list-children-card .card-title {
+  font-weight: 600;
+  font-size: 0.95rem;
+}
+
+.list-children-card .card-desc {
+  margin-top: 0.25rem;
+  font-size: 0.85rem;
+  color: var(--twinkle-text-secondary);
+}
+
+.dark .list-children-card {
+  border-color: #334155;
+}
+
+.dark .list-children-card:hover {
+  border-color: var(--twinkle-primary-light);
+}
+

assets/jsconfig.json

@@ -3,9 +3,9 @@
   "baseUrl": ".",
   "paths": {
    "*": [
-    "../../../../Library/Caches/hugo_cache/modules/filecache/modules/pkg/mod/github.com/!hugo!blox/kit/modules/blox@v0.0.0-20260124040029-77f7678f08ac/assets/*",
-    "../../../../Library/Caches/hugo_cache/modules/filecache/modules/pkg/mod/github.com/!hugo!blox/kit/modules/blox@v0.0.0-20260124040029-77f7678f08ac/blox/*",
-    "../../../../Library/Caches/hugo_cache/modules/filecache/modules/pkg/mod/github.com/!hugo!blox/kit/modules/blox@v0.0.0-20260124040029-77f7678f08ac/blox/shared/js/*"
+    "../../../../../../../root/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/!hugo!blox/kit/modules/blox@v0.0.0-20260124040029-77f7678f08ac/assets/*",
+    "../../../../../../../root/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/!hugo!blox/kit/modules/blox@v0.0.0-20260124040029-77f7678f08ac/blox/*",
+    "../../../../../../../root/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/!hugo!blox/kit/modules/blox@v0.0.0-20260124040029-77f7678f08ac/blox/shared/js/*"
    ]
   }
  }

config/_default/hugo.yaml

@@ -97,7 +97,7 @@ timeout: 600000
 taxonomies:
   tag: tags
   category: categories
-  author: authors
+
 markup:
   _merge: deep
 related:

config/_default/menus.yaml

@@ -5,18 +5,26 @@ main:
   - name: Home
     url: /
     weight: 10
+  - name: Quick Start
+    url: /docs/getting-started/
+    weight: 15
   - name: Documentation
-    url: docs/
+    url: /docs/
     weight: 20
   - name: Blog
-    url: blog/
+    url: /blog/
     weight: 30
-  - name: Showcase
-    url: showcase/
+  - name: Cookbook
+    url: /showcase/
     weight: 40
   - name: Community
-    url: community/
+    url: /community/
     weight: 50
+  - name: GitHub
+    url: https://github.com/modelscope/twinkle
+    weight: 60
+    params:
+      icon: github
 
 sidebar:
   - identifier: more
@@ -27,7 +35,7 @@ sidebar:
   - identifier: community
     name: "Community"
     # url matches main nav; avoids pageRef edge cases with multilingual + base path
-    url: community/
+    url: /community/
     weight: 2
   - identifier: github
     name: "GitHub ↗"

config/_default/menus.zh.yaml

@@ -4,18 +4,26 @@ main:
   - name: 首页
     url: /
     weight: 10
+  - name: 快速上手
+    url: /docs/getting-started/
+    weight: 15
   - name: 文档
-    url: docs/
+    url: /docs/
     weight: 20
   - name: 博客
-    url: blog/
+    url: /blog/
     weight: 30
-  - name: 案例展示
-    url: showcase/
+  - name: Cookbook
+    url: /showcase/
     weight: 40
   - name: 社区
-    url: community/
+    url: /community/
     weight: 50
+  - name: GitHub
+    url: https://github.com/modelscope/twinkle
+    weight: 60
+    params:
+      icon: github
 
 sidebar:
   - identifier: more
@@ -26,7 +34,7 @@ sidebar:
   - identifier: community
     name: "社区"
     # Use url (not pageRef): pageRef breaks on zh pages → /zh/twinkle-web/zh/community/
-    url: community/
+    url: /community/
     weight: 2
   - identifier: github
     name: "GitHub ↗"