Improve docs UX: homepage redesign, navigation, and per-page actions#316
Open
King31T wants to merge 8 commits intotronprotocol:masterfrom
Open
Improve docs UX: homepage redesign, navigation, and per-page actions#316King31T wants to merge 8 commits intotronprotocol:masterfrom
King31T wants to merge 8 commits intotronprotocol:masterfrom
Conversation
Set edit_uri to edit/master/docs/ and add repo_name so Material renders the top-bar repository link with a friendly label. Enable content.action.edit and content.action.view to expose pencil and eye icons on every page, letting readers jump directly to the source on GitHub or open it in the web editor.
Comment out toc.integrate so the table of contents returns to its own right-hand sidebar, freeing the left sidebar to carry only site navigation. Add navigation.tracking and toc.follow so the URL anchor and the right-side TOC stay in sync with the current section while scrolling, which matters most on long API pages such as docs/api/json-rpc.md and docs/api/http.md. Custom scripts (toc.js, nav-toc.js) and related styles are left in place; their cleanup will be evaluated in a follow-up.
The mobile footer override at the bottom of docs/stylesheets/extra.css opened a @media screen and (max-width: 44.984375em) block but never closed it. Browsers were lenient enough to render the page correctly, but any rule appended after this point would silently fall inside the media query and only apply on narrow viewports. Add the missing brace so future additions behave as expected.
Add mkdocs-git-revision-date-localized to surface a clock icon and localized date at the bottom of every page, so readers can tell whether content describes an older java-tron release or a current one. Switch theme.language to zh so Material's surrounding labels render in Chinese as well: the timestamp tooltip becomes 最后更新, prev/next captions become 上一页/下一页, the search placeholder becomes 搜索, and the edit/view-source action tooltips are translated. Update the GitHub Pages workflow to fetch the full git history; without fetch-depth: 0 the plugin would resolve every page's mtime to the build moment instead of the file's last commit. Pin the plugin to 1.5.1 to match the project's convention of explicit version pins.
Add content.code.copy to the Material features list so every code block gets a clipboard icon in the top-right corner. The site is dominated by HTTP, gRPC, and JSON-RPC request samples; a copy button removes the fiddly manual-select step readers face today on long curl payloads. The button tooltip and copied confirmation render in Chinese automatically thanks to the language: zh setting added earlier.
Enable search.share so the search dialog renders a share icon next to the query input. Clicking it copies the current page URL with the active query appended as ?q=..., which makes it easier to send a teammate a link that opens directly on a specific search result.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/index.md).navigation.indexes(section index.md as landing page), per-page "last updated" date, Chinese UI strings, and per-page "edit this page / view source" actions.@mediablock inextra.css; restore the right-side TOC by disablingtoc.integrate.gh-pages.ymlfor the new build requirements.Commits
Test plan
mkdocs servelocally and confirm the homepage, role cards, and topic index render correctly.index.mdbehave as expected withnavigation.indexesenabled.gh-pagesdeployment succeeds.