Fix urls and add small enhancements - #8
Open
fqixiang wants to merge 8 commits into
Open
Conversation
Add --accept-timeouts and --accept "100..=103,200..=299,403" to .github/workflows/weekly-link-check.yml so the weekly link-check workflow treats timeouts and specified HTTP status ranges/codes as acceptable, reducing false positives.
Configure MkDocs to use a local theme overrides directory by adding theme.custom_dir: theme_overrides. This allows project-specific modifications to the gitbook theme without altering the upstream theme files.
Introduce a new base.html theme override providing the main layout for the site. The template sets site meta, loads styles (including extra_css), conditionally includes search UI when the 'search' plugin is enabled, includes navigation and content templates, renders prev/next page links, and includes script tags (including extra_javascript) plus theme/GitBook JS. This file customizes the MkDocs/GitBook theme structure and page shell.
Introduce a new "Social Science and Humanities Research with LLMs" section that highlights example research projects from the ODISSEI SoDa team, including BiodiversityASSET, Future Time Orientation and Life Project, LLMs for Self-Regulated Learning, Judicial Signals, and Historical Disease Database, with a link to the SoDa projects overview. Also tidy up surrounding section separators and spacing in docs/index.md.
Reorganize docs/index.md to surface the 'What You Will Find Here' and 'How To Read This Guide' sections near the top for better discoverability. The duplicate instance later in the file was removed. Content includes the usage-mode bullets and three-step reading guide; no functional changes.
Add a Decision Tree section with an SVG to help readers find the right chapter, introduce anchor IDs for the chapter overview and decision-tree, and adjust the introductory navigation steps and phrasing. The changes reorganize the top-level guidance (pointing users to the decision tree and chapter overview), update the chapters heading to include an ID, and tweak wording for clarity.
There was a problem hiding this comment.
Pull request overview
This PR updates the MkDocs site to improve documentation navigation and the homepage structure, while also making the weekly link-check workflow less noisy and fixing a redirected external URL. It introduces a theme override to add per-page previous/next navigation buttons and refreshes the homepage content with a decision-tree visual and SSH-oriented examples.
Changes:
- Added a MkDocs GitBook theme override to enable previous/next page navigation.
- Restructured the documentation homepage and added a decision tree SVG plus additional SSH project examples.
- Adjusted link-checking to accept timeouts/403s and fixed a redirected SURF link.
Reviewed changes
Copilot reviewed 5 out of 6 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
theme_overrides/base.html |
New base template override to add navigation buttons and customize page HTML layout. |
mkdocs.yml |
Points MkDocs theme to use theme_overrides/ as custom_dir. |
docs/index.md |
Homepage restructuring, new decision-tree section, and added SSH examples. |
docs/img/decision-tree.svg |
Adds the decision tree visual referenced on the homepage. |
docs/institutional-resources/apis.md |
Fixes the SURF AI Hub / WiLLMa link to the correct URL casing. |
.github/workflows/weekly-link-check.yml |
Makes lychee accept timeouts and HTTP 403 to reduce false positives. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+119
to
+121
| </div> <!-- end of book-body --> | ||
|
|
||
| {%- block scripts %} |
| <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no"> | ||
| <meta name="apple-mobile-web-app-capable" content="yes"> | ||
| <meta name="apple-mobile-web-app-status-bar-style" content="black"> | ||
| <meta rel="next" href="" /> |
| <!-- Title --> | ||
| <h1> | ||
| <i class="fa fa-circle-o-notch fa-spin"></i> | ||
| <a href="." ></a> |
| {%- block search_button %} | ||
| {%- if 'search' in config['plugins'] %} | ||
| <div id="book-search-input" role="search"> | ||
| <input type="text" placeholder="Type to search" /> |
| 1. Start with the chapter overviews. | ||
| > Check out the [Decision Tree](#decision-tree) to find the page that matches your situation. | ||
|
|
||
| Alternative, |
Comment on lines
+47
to
+48
| Focuses on six usage modes: | ||
| >chat, dashboards, APIs, local deployments, remote deployments, and HPC. |
| {% if config.site_author %}<meta name="author" content="{{ config.site_author }}">{% endif %} | ||
| <link rel="shortcut icon" href="{{ base_url }}/images/favicon.ico" type="image/x-icon"> | ||
| <meta name="HandheldFriendly" content="true"/> | ||
| <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no"> |
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
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.
fix #2 by adding navigation buttons (previous or next) on each page
fix #3 improve formatting/structure for the home page
fix #4 add a decision tree visual to the home page
fix #5 add SSH examples from SoDa on home page
fix #7 remove warning for timeout and 403 links; fix one redirected link
In detail, this pull request introduces several improvements to the documentation and site theming, focusing on enhancing navigation, clarity, and user experience. The most significant changes include the addition of a custom theme override, major content and structure updates to the documentation homepage, and improvements to link checking and API documentation.
Documentation content and navigation improvements:
docs/index.md: The homepage was restructured to add a prominent decision tree for easier navigation, a new section highlighting social science and humanities research use cases, and clearer instructions for getting started. The chapter overview and usage mode descriptions were also clarified. [1] [2]docs/index.md: Updated the "How To Read This Guide" section to recommend the new decision tree and clarified the step-by-step guidance for readers.docs/institutional-resources/apis.md: Fixed a broken link in the SURF AI Hub / WiLLMa example to ensure users are directed to the correct onboarding information.Site theming and technical improvements:
mkdocs.yml,theme_overrides/base.html: Introduced a custom theme override by adding atheme_overridesdirectory and a newbase.htmltemplate, allowing for further customization of the site's appearance and layout. [1] [2]Link checking and validation:
.github/workflows/weekly-link-check.yml: Improved the link checking workflow by accepting additional HTTP status codes and timeouts, making the link validation process more robust.