Skip to content

Update Data Docs link - #39

Draft
forsyth2 wants to merge 1 commit into
mainfrom
update-data-docs-link
Draft

forsyth2 wants to merge 1 commit into
mainfrom
update-data-docs-link

Conversation

@forsyth2

Copy link
Copy Markdown
Contributor

Renata had the following suggestions for changing the DataDocs link:

  1. The link should be "Data" rather than "DataDocs"
  2. The link should come after Emulators.
  3. Ideally, the link should go to /data

@forsyth2 forsyth2 self-assigned this Nov 19, 2026
@forsyth2 forsyth2 added the documentation Improvements or additions to documentation label Nov 19, 2026
@forsyth2
forsyth2 force-pushed the update-data-docs-link branch from 1471809 to f64b11f Compare November 19, 2026 01:15
@github-actions

Copy link
Copy Markdown
PR Preview Action v1.8.2

QR code for preview link

🚀 View preview at
https://E3SM-Project.github.io/pr-preview/pr-39/

Built to branch gh-pages at 2026-11-19 01:15 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

@forsyth2

Copy link
Copy Markdown
Contributor Author

The first commit, f64b11f, addresses (1) and (2). As for (3), Claude suggests the following three options:

  1. Add a redirect stub in the main site repo (easiest)
  2. Rename the repo to data -- I think this is out of the question; that would require renaming the entire e3sm_data_docs repo to the very generic data.
  3. Build the docs into the main site -- also out of the question, DataDocs' docs can't be kept in a completely different repo.

This link rename also relates to E3SM-Project/e3sm_data_docs#78, raised previously by @mahf708.

@forsyth2

Copy link
Copy Markdown
Contributor Author

Claude's suggestion:

Proposed change: serve the data docs at https://docs.e3sm.org/data/

The main site is built with MkDocs, which copies non-Markdown files from docs/ into the built site unchanged. So a small HTML redirect stub is enough. No renaming or new tooling is needed.

Steps

  1. Create docs/data/index.html in E3SM-Project.github.io with the following content:

    <!DOCTYPE html>
    <html lang="en">
    <head>
      <meta charset="utf-8">
      <title>E3SM Data Docs</title>
      <link rel="canonical" href="https://docs.e3sm.org/e3sm_data_docs/_build/html/index.html">
      <meta http-equiv="refresh" content="0; url=https://docs.e3sm.org/e3sm_data_docs/_build/html/index.html">
    </head>
    <body>
      <p>Redirecting to the
        <a href="https://docs.e3sm.org/e3sm_data_docs/_build/html/index.html">E3SM Data Docs</a>…
      </p>
    </body>
    </html>

    The target is absolute so it doesn't depend on relative path resolution. The canonical link tells search engines which URL is the real one, and the body link covers browsers that block meta refresh.

  2. Update the link in docs/index.md:

    -- [Data](https://e3sm-project.github.io/e3sm_data_docs/_build/html/index.html) - Output from major E3SM simulations
    +- [Data](https://docs.e3sm.org/data/) - Output from major E3SM simulations

    The trailing slash avoids a GitHub Pages redirect hop from /data to /data/. https://docs.e3sm.org/data will still work for anyone who types it without the slash.

  3. Check for conflicts before merging:

    • There is no docs/data/index.md or docs/data.md (MkDocs would try to build a page at the same path).
    • mkdocs.yml doesn't list data/ under exclude_docs (or a similar setting, depending on the MkDocs version).
  4. Deploy and test: after the site rebuilds, open https://docs.e3sm.org/data/ in a private window and confirm it lands on the data docs. Also click the Data link on https://docs.e3sm.org/.

Notes

  • After the redirect, the address bar will show the long .../e3sm_data_docs/_build/html/index.html URL. Only the entry-point link and anything bookmarked or shared from docs.e3sm.org will use the short /data/ form.

  • Alternative: if the project already uses (or is willing to add) the mkdocs-redirects plugin, step 1 can be replaced with this in mkdocs.yml:

    plugins:
      - redirects:
          redirect_maps:
            'data/index.md': 'https://docs.e3sm.org/e3sm_data_docs/_build/html/index.html'

    The plain HTML file needs no new dependencies, so it's the simpler starting point.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants