跳至主要內容

Article Page Redesign Implementation Plan

2026/4/16大约 6 分钟

Article Page Redesign Implementation Plan

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Rebuild IFZPress article pages around a正文优先 layout with a stable right sidebar, compact default TOC, complex-TOC fallback rail, and a persistent back-to-top button without disturbing the existing homepage and publishing flow.

Architecture: Keep the existing vuepress-theme-hope theme and global blog routes. Implement article-page behavior with a small VuePress client config plus focused DOM helpers, and move article-specific CSS into a dedicated stylesheet so the current all-in-one index.scss can keep homepage / archive rules while article layout logic lives in one place. Use the existing theme navbar slots and blog sidebar wrapper instead of introducing a custom layout or a new search stack.

Tech Stack: VuePress v2 RC, vuepress-theme-hope, Vite bundler, SCSS, small client-side DOM hooks via .vuepress/client.js

Chunk 1: Client Hooks And Article-State Plumbing

Task 1: Add a VuePress client entry for article-page behaviors

Files:

  • Create: docs/.vuepress/client.js

  • Create: docs/.vuepress/client/article-page-data.js

  • Create: docs/.vuepress/client/article-page-dom.js

  • Verify: package.json

  • [ ] Step 1: Confirm the current build is green before adding any client code

Run: npm run docs:build

Expected: build completes successfully and outputs docs/.vuepress/dist

  • [ ] Step 2: Create docs/.vuepress/client/article-page-data.js to centralize sidebar copy

Add one exported object for:

  • About title and description
  • Featured article links
  • WeChat distribution title and description

Keep the file data-only so copy tweaks do not require reading DOM logic.

  • [ ] Step 3: Create docs/.vuepress/client/article-page-dom.js for article-page DOM helpers

Implement small focused functions instead of one long script:

  • isArticlePage(route)
    Return true only for /posts/ article routes.
  • findArticleShell()
    Resolve the page title, page content, TOC, and blog sidebar wrapper nodes safely.
  • renderSidebarExtras(data)
    Append one continuous sidebar block under the existing blogger info wrapper.
  • ensureBackToTopButton()
    Inject one reusable button into document.body.
  • updateComplexTocState()
    Count TOC items and toggle a body class such as ifz-complex-toc.
  • syncArticleChrome(route)
    Master function that adds / removes article-page classes and mounts helpers.

Implementation notes:

  • Reuse injected DOM when navigating client-side; do not duplicate nodes on every route change.

  • Add a debug override via URL query, e.g. ?ifzToc=complex, so complex-TOC styling can be verified even though the repo currently has only short posts.

  • Remove article-only classes on non-article pages so the homepage and archive pages are unaffected.

  • [ ] Step 4: Create docs/.vuepress/client.js and wire route updates into the DOM helpers

Use the official VuePress client config entry:

import { defineClientConfig } from "vuepress/client";
import { syncArticleChrome } from "./client/article-page-dom.js";

export default defineClientConfig({
  enhance({ router }) {
    router.afterEach((to) => {
      queueMicrotask(() => syncArticleChrome(to));
    });
  },
  setup() {
    if (typeof window !== "undefined") {
      queueMicrotask(() => {
        syncArticleChrome(window.location);
      });
    }
  }
});

Adjust the final implementation if the router payload shape differs, but keep the entry file this small.

  • [ ] Step 5: Run the build again to catch import / hydration issues

Run: npm run docs:build

Expected: build completes successfully with no missing-module or client-config errors

  • [ ] Step 6: Commit the plumbing before touching styles
git add docs/.vuepress/client.js docs/.vuepress/client/article-page-data.js docs/.vuepress/client/article-page-dom.js
git commit -m "feat: add article page client hooks"

Chunk 2: Article Layout And Navbar Restyling

Task 2: Split article-specific CSS out of the current monolithic stylesheet

Files:

  • Create: docs/.vuepress/styles/article-page.scss

  • Modify: docs/.vuepress/styles/index.scss:1-40

  • Modify: docs/.vuepress/styles/index.scss:283-625

  • Modify: docs/.vuepress/styles/index.scss:839-924

  • [ ] Step 1: Add an import for the new article stylesheet near the top of index.scss

Keep shared tokens and homepage styles in index.scss, but move article-page rules into a dedicated file:

@import "./article-page";

Do not move color variables or homepage-specific sections out of index.scss.

  • [ ] Step 2: Create docs/.vuepress/styles/article-page.scss and migrate the current article-only selectors

Start by moving the current article-specific blocks out of index.scss, especially:

  • .vp-page .vp-blog-info-wrapper
  • .vp-page-title
  • [vp-toc], .vp-toc-placeholder, #toc
  • [vp-content]:not(.custom) #markdown-content
  • .vp-page-meta, .vp-page-nav
  • relevant responsive overrides in the 1279 / 959 / 719 breakpoints

This task is a file-organization move first; do not redesign everything yet.

  • [ ] Step 3: Rebuild to ensure the stylesheet split does not change behavior accidentally

Run: npm run docs:build

Expected: build succeeds and the generated CSS still includes article-page rules

  • [ ] Step 4: Commit the stylesheet split
git add docs/.vuepress/styles/index.scss docs/.vuepress/styles/article-page.scss
git commit -m "refactor: isolate article page styles"

Task 3: Restyle the article page around a continuous reading shell

Files:

  • Modify: docs/.vuepress/styles/article-page.scss

  • Verify: docs/posts/2026-02-05-deploy-openclaw.md

  • Verify: docs/posts/2026-02-03-decaps-cms-workflow.md

  • [ ] Step 1: Rework the article navbar alignment without adding a new feature stack

Use CSS against the existing Hope navbar structure so article pages feel closer to Josh’s layout:

  • keep brand on the left
  • relax the centered “homepage portal” feel
  • move utility controls to the far right
  • keep the solution compatible with the existing navbarLayout in config.js

Do not add a new search plugin in this iteration.

  • [ ] Step 2: Replace the card-heavy article shell with a continuous page surface

Update the article page selectors so the result feels like one reading environment instead of stacked boxes:

  • reduce heavy card borders / rounded containers around the page title and body
  • favor spacing, thin separators, and restrained background shifts
  • keep the article body dominant over the sidebar

Use the approved direction:

-正文主列更强
-右侧栏更轻
-整体不回到“玻璃卡片拼装”

  • [ ] Step 3: Restyle the right sidebar as one continuous column

Style the existing blogger info wrapper plus injected extras so it reads as one column:

  • About section first
  • Featured content second
  • WeChat distribution third

Important:

  • do not style these as three disconnected cards

  • use subtle section dividers instead

  • keep the right rail visually subordinate to the正文

  • [ ] Step 4: Redesign the default TOC as a compact intro aid

Keep the default TOC in the main column under the intro / lead area:

  • show only the current large-section navigation treatment

  • reduce panel weight

  • remove the “secondary full sidebar” feeling

  • preserve anchor usability

  • [ ] Step 5: Keep the article body and page-nav continuous

Refine:

  • title / meta spacing
  • first paragraph as lead
  • h2 / h3 spacing
  • code block weight
  • prev / next navigation integration

The final result should feel like one continuous article layout, not a title card + content card + nav card stack.

  • [ ] Step 6: Verify the redesigned layout on at least two real article pages

Run: npm run docs:build

Then preview the built site and manually inspect:

  • http://127.0.0.1:8086/posts/2026-02-05-deploy-openclaw.html
  • http://127.0.0.1:8086/posts/2026-02-03-decaps-cms-workflow.html

Check:

  • the navbar feels lighter

  • the right rail is stable

  • the default TOC is compact

  • the homepage still looks unchanged

  • [ ] Step 7: Commit the article shell redesign

git add docs/.vuepress/styles/article-page.scss docs/.vuepress/styles/index.scss
git commit -m "feat: redesign article page layout"

Chunk 3: Complex TOC Mode And Persistent Utilities

Task 4: Implement complex-TOC mode, hover rail behavior, and back-to-top utility

Files:

  • Modify: docs/.vuepress/client/article-page-dom.js

  • Modify: docs/.vuepress/styles/article-page.scss

  • [ ] Step 1: Add the complex-TOC threshold logic in the DOM helper

Use one function to classify TOC state:

const isComplexToc = tocItems.length >= 6 || hasNestedHeadings;
document.body.classList.toggle("ifz-complex-toc", isComplexToc || forceComplexPreview);

Guidelines:

  • nested headings means the rendered TOC includes lower levels beyond the default simple list

  • preserve the URL query override ?ifzToc=complex

  • never enable complex mode on non-article pages

  • [ ] Step 2: Add the left transparent hover rail styles

Style the complex-mode rail so it:

  • sits collapsed on the left edge by default

  • stays translucent / low-contrast when idle

  • expands only on hover / focus

  • does not cover the正文 when inactive

  • disappears on tablet / mobile breakpoints

  • [ ] Step 3: Add the persistent back-to-top button behavior

Implement one reusable button that:

  • is injected once
  • appears only on article pages
  • scrolls smoothly to top
  • remains fixed in the bottom-right corner

Avoid adding multiple listeners on route changes.

  • [ ] Step 4: Build and manually verify both TOC modes

Run: npm run docs:build

Manual checks:

  • default mode: http://127.0.0.1:8086/posts/2026-02-05-deploy-openclaw.html
  • forced complex preview: http://127.0.0.1:8086/posts/2026-02-05-deploy-openclaw.html?ifzToc=complex

Check:

  • default mode has no left hover rail

  • forced complex preview shows the collapsed left rail

  • hover expands the rail cleanly

  • the back-to-top button is visible and works in both modes

  • [ ] Step 5: Commit the interaction layer

git add docs/.vuepress/client.js docs/.vuepress/client/article-page-dom.js docs/.vuepress/styles/article-page.scss
git commit -m "feat: add advanced article page navigation"

Chunk 4: Final Verification And Documentation Sync

Task 5: Capture the shipped behavior in repo docs and run the final regression pass

Files:

  • Modify: BLOG_REDESIGN_SUMMARY.md

  • Verify: docs/.vuepress/config.js

  • Verify: docs/.vuepress/styles/index.scss

  • Verify: docs/.vuepress/styles/article-page.scss

  • Verify: docs/.vuepress/client.js

  • Verify: docs/.vuepress/client/article-page-data.js

  • Verify: docs/.vuepress/client/article-page-dom.js

  • [ ] Step 1: Update BLOG_REDESIGN_SUMMARY.md with the article-page redesign outcome

Add a short new section that records:

  • homepage left as-is

  • article pages redesigned around正文优先

  • stable right sidebar now includes featured content and WeChat distribution

  • complex TOC mode exists only for long / nested TOCs

  • back-to-top button added

  • [ ] Step 2: Run the full build one final time

Run: npm run docs:build

Expected: build succeeds with no new warnings beyond pre-existing theme warnings

  • [ ] Step 3: Run the final manual regression checklist

Preview and inspect:

  • homepage: http://127.0.0.1:8086/
  • standard article: http://127.0.0.1:8086/posts/2026-02-05-deploy-openclaw.html
  • complex TOC preview: http://127.0.0.1:8086/posts/2026-02-05-deploy-openclaw.html?ifzToc=complex
  • second article sanity check: http://127.0.0.1:8086/posts/2026-02-04-build-and-deploy.html

Checklist:

  • homepage is visually unchanged except any intentional shared-sidebar polish

  • article navbar is calmer and better aligned

  • right rail is continuous instead of card-stacked

  • default TOC stays compact

  • complex TOC rail only appears in forced preview / truly complex cases

  • back-to-top button works

  • no layout breakage on tablet and mobile widths

  • [ ] Step 4: Commit the documentation sync and final verification state

git add BLOG_REDESIGN_SUMMARY.md docs/.vuepress/styles/index.scss docs/.vuepress/styles/article-page.scss docs/.vuepress/client.js docs/.vuepress/client/article-page-data.js docs/.vuepress/client/article-page-dom.js
git commit -m "docs: record article page redesign"

Plan complete and saved to docs/superpowers/plans/2026-04-16-article-page-redesign.md. Ready to execute?

最近更新:
贡献者: blog