feat(gh-pages): 💄 add sidebar

.github/workflows/build-gh-pages.yml

@@ -2,11 +2,11 @@ name: build-gh-pages
 
 on:
   pull_request:
-    branches: [dev, main]
+    branches: [dev, main, gh-pages]
     paths-ignore:
       - "src/**"
   push:
-    branches: [dev, main]
+    branches: [dev, main, gh-pages]
     paths-ignore:
       - "src/**"
 

.github/workflows/gh-pages.yml

@@ -2,7 +2,7 @@ name: Deploy Jekyll and Avalonia WASM demo
 
 on:
   push:
-    branches: ["main"]
+    branches: ["main", "gh-pages"]
     paths-ignore:
       - "src/**"
 
@@ -66,7 +66,7 @@ jobs:
       - name: Checkout demo repository
         uses: actions/checkout@v4
         with:
-          repository: eesast/dotnet-workshop-solution
+          repository: ${{ vars.DOTNET_WORKSHOP_SOLUTION_REPOSITORY }}
           token: ${{ secrets.DOTNET_WORKSHOP_SOLUTION_READ }}
           path: dotnet-workshop-solution
           persist-credentials: false

_data/navigation.yml

@@ -0,0 +1,46 @@
+label: 文档导航
+home_label: 项目主页
+open_label: 展开导航
+close_label: 隐藏导航
+home_url: /
+sections:
+  - title: "`00-prepare`"
+    items:
+      - title: Guidance
+        url: /docs/00-prepare/guidance.html
+      - title: Tasks
+        url: /docs/00-prepare/tasks.html
+  - title: "`01-basic`"
+    items:
+      - title: Guidance
+        url: /docs/01-basic/guidance.html
+      - title: Tasks
+        url: /docs/01-basic/tasks.html
+  - title: "`02-multithreading`"
+    items:
+      - title: Guidance
+        url: /docs/02-multithreading/guidance.html
+      - title: Tasks
+        url: /docs/02-multithreading/tasks.html
+  - title: "`03-async-grpc`"
+    items:
+      - title: Guidance
+        url: /docs/03-async-grpc/guidance.html
+      - title: Tasks
+        url: /docs/03-async-grpc/tasks.html
+  - title: "`04-avalonia`"
+    items:
+      - title: Guidance
+        url: /docs/04-avalonia/guidance.html
+      - title: Tasks
+        url: /docs/04-avalonia/tasks.html
+  - title: "`05-advanced`"
+    items:
+      - title: Guidance
+        url: /docs/05-advanced/guidance.html
+      - title: Tasks
+        url: /docs/05-advanced/tasks.html
+  - title: "`appendix`"
+    items:
+      - title: 附录 A：部分名词不同语言对照表
+        url: /docs/appendix/appendix-a-glossary.html

_includes/sidebar.html

@@ -0,0 +1,58 @@
+<button
+  type="button"
+  class="sidebar-open-button"
+  aria-label="{{ include.navigation.open_label }}"
+  title="{{ include.navigation.open_label }}"
+  aria-controls="sidebar-panel"
+  aria-expanded="false">
+  <span aria-hidden="true">☰</span>
+  <span class="sidebar-open-label">{{ include.navigation.open_label }}</span>
+</button>
+
+<aside id="sidebar-panel" class="sidebar" aria-hidden="false">
+  <button
+    type="button"
+    class="sidebar-close-button"
+    aria-controls="sidebar-panel"
+    aria-expanded="true">
+    <span aria-hidden="true">‹</span>
+    <span>{{ include.navigation.close_label }}</span>
+  </button>
+
+  <nav aria-label="{{ include.navigation.label }}">
+    <a class="sidebar-home" href="{{ include.navigation.home_url | relative_url }}">
+      {{ include.navigation.home_label }}
+    </a>
+
+    {% for section in include.navigation.sections %}
+      {% assign section_is_active = false %}
+      {% for item in section.items %}
+        {% if page.url == item.url %}
+          {% assign section_is_active = true %}
+        {% endif %}
+      {% endfor %}
+
+      <details class="sidebar-section"{% if section_is_active %} open{% endif %}>
+        <summary>{{ section.title | markdownify | remove: '<p>' | remove: '</p>' }}</summary>
+        <ul>
+          {% for item in section.items %}
+            <li>
+              {% if page.url == item.url %}
+                <span class="active" aria-current="page">{{ item.title | markdownify | remove: '<p>' | remove: '</p>' }}</span>
+              {% else %}
+                <a href="{{ item.url | relative_url }}">{{ item.title | markdownify | remove: '<p>' | remove: '</p>' }}</a>
+              {% endif %}
+            </li>
+          {% endfor %}
+        </ul>
+      </details>
+    {% endfor %}
+  </nav>
+</aside>
+
+<button
+  type="button"
+  class="sidebar-backdrop"
+  aria-label="{{ include.navigation.close_label }}"
+  tabindex="-1">
+</button>

_layouts/default.html

@@ -17,6 +17,8 @@
         src="{{ '/assets/js/prepare.js?v=' | append: site.github.build_revision | relative_url }}"></script>
     <script type="text/javascript"
         src="{{ '/assets/js/colored-block.js?v=' | append: site.github.build_revision | relative_url }}"></script>
+    <script type="text/javascript" defer
+        src="{{ '/assets/js/sidebar.js?v=' | append: site.github.build_revision | relative_url }}"></script>
 
     {% include head-custom.html %}
 
@@ -79,7 +81,16 @@ <h2>{{ site.description | default: site.github.project_tagline }}</h2>
         </div>
     </header>
 
-    <div class="container">
+    {% assign page_path_parts = page.url | split: '/' %}
+    {% assign show_sidebar = false %}
+    {% if page_path_parts[1] == 'docs' and page.sidebar != false %}
+        {% assign show_sidebar = true %}
+    {% endif %}
+
+    <div class="container content-layout{% if show_sidebar %} has-sidebar{% endif %}">
+        {% if show_sidebar %}
+            {% include sidebar.html navigation=site.data.navigation %}
+        {% endif %}
         <section id="main_content">
             {{ content }}
         </section>

assets/css/custom.css

@@ -35,6 +35,100 @@ code {
   display: inline-block;
 }
 
+.content-layout.has-sidebar {
+  width: 94%;
+  max-width: 1400px;
+  display: grid;
+  grid-template-columns: minmax(220px, 280px) minmax(0, 1fr);
+  gap: 40px;
+  align-items: start;
+}
+
+.content-layout.has-sidebar.sidebar-collapsed {
+  grid-template-columns: 52px minmax(0, 1fr);
+}
+
+.sidebar-open-button {
+  display: none;
+  padding: 10px 12px;
+}
+
+.sidebar-collapsed .sidebar-open-button {
+  position: sticky;
+  top: 20px;
+  display: flex;
+  width: 44px;
+  height: 44px;
+  align-items: center;
+  justify-content: center;
+}
+
+.sidebar-open-label {
+  display: none;
+}
+
+.sidebar {
+  position: sticky;
+  top: 20px;
+  max-height: calc(100vh - 40px);
+  overflow-y: auto;
+  padding: 16px;
+}
+
+.sidebar-collapsed .sidebar {
+  display: none;
+}
+
+.sidebar-close-button {
+  display: flex;
+  width: 100%;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 16px;
+  padding: 8px 10px;
+  text-align: left;
+}
+
+.sidebar-backdrop {
+  display: none;
+}
+
+.sidebar-home {
+  display: block;
+  margin-bottom: 16px;
+}
+
+.sidebar-section {
+  margin-bottom: 20px;
+}
+
+.sidebar-section:last-child {
+  margin-bottom: 0;
+}
+
+.sidebar-section summary {
+  padding-bottom: 6px;
+}
+
+.sidebar-section[open] summary {
+  margin-bottom: 8px;
+}
+
+.sidebar-section ul {
+  margin: 0;
+  padding-left: 5px;
+}
+
+.sidebar-section li {
+  margin: 6px 0;
+}
+
+.sidebar .active {
+  display: block;
+  margin-left: -8px;
+  padding: 4px 8px;
+}
+
 @media screen and (max-width: 768px) {
   .head_wrapper {
     display: flex;
@@ -49,4 +143,66 @@ code {
     align-items: center;
     justify-content: center;
   }
+
+  .content-layout.has-sidebar {
+    width: 90%;
+    display: block;
+  }
+
+  .content-layout.has-sidebar.sidebar-collapsed {
+    display: block;
+  }
+
+  .sidebar-open-button,
+  .sidebar-collapsed .sidebar-open-button {
+    position: fixed;
+    left: 16px;
+    bottom: 16px;
+    z-index: 1001;
+    display: flex;
+    width: auto;
+    height: auto;
+    align-items: center;
+    gap: 8px;
+  }
+
+  .sidebar-open-label {
+    display: inline;
+  }
+
+  .sidebar-mobile-open .sidebar-open-button {
+    display: none;
+  }
+
+  .sidebar {
+    position: fixed;
+    top: 0;
+    bottom: 0;
+    left: 0;
+    z-index: 1002;
+    display: block;
+    width: min(86vw, 340px);
+    max-height: none;
+    overflow-y: auto;
+    box-sizing: border-box;
+    transform: translateX(-100%);
+    visibility: hidden;
+    transition: transform 180ms ease, visibility 180ms ease;
+  }
+
+  .sidebar-mobile-open .sidebar {
+    transform: translateX(0);
+    visibility: visible;
+  }
+
+  .sidebar-mobile-open .sidebar-backdrop {
+    position: fixed;
+    inset: 0;
+    z-index: 1000;
+    display: block;
+  }
+
+  body.sidebar-scroll-locked {
+    overflow: hidden;
+  }
 }