Skip to content

Fix #4147: Broken links at https://redis.github.io/jedis/#4285

Merged
ggivo merged 4 commits intoredis:masterfrom
SwapnaliY16:fix-issue-4147
Sep 29, 2025
Merged

Fix #4147: Broken links at https://redis.github.io/jedis/#4285
ggivo merged 4 commits intoredis:masterfrom
SwapnaliY16:fix-issue-4147

Conversation

@SwapnaliY16
Copy link
Contributor

@SwapnaliY16 SwapnaliY16 commented Sep 17, 2025

Summary

Fixes issue #4147 by keeping two separate files:

  • README.md for GitHub (with links relative to the repo root)
  • docs/index.md for MkDocs (with links relative to the docs/ directory).

Changes

  • Copy the content from README.md to docs/index.md instead of symlinks {% include 'README.md' %}.
  • Update all links in docs/index.md to be relative to the docs/ directory (e.g., advanced-usage.md) by ensuring all referenced .md files exist in docs/.
  • Update the nav section in mkdocs.yml to include all documentation pages.

Outcome

This approach keeps both your GitHub and MkDocs documentation working and avoids broken links.

Testing

  • Installed MkDocs and required plugins:
pip install mkdocs
pip install mkdocs-macros-plugin
pip install mkdocs-material
  • Ran mkdocs serve in the project root successfully with one warning:
INFO    -  Building documentation...
INFO    -  [macros] - No default module `main` found
INFO    -  [macros] - Includes directory: .
INFO    -  [macros] - Config variables: ['extra', 'config', 'environment', 'plugin', 'git', 'macros', 'filters', 'filters_builtin']
INFO    -  [macros] - Config macros: ['context', 'macros_info', 'now', 'fix_url']
INFO    -  [macros] - Config filters: ['pretty', 'relative_url']
INFO    -  Cleaning site directory
WARNING -  Excluding 'README.md' from the site because it conflicts with 'index.md'.
INFO    -  Documentation built in 0.78 seconds
INFO    -  [macros] - We will also watch: ['.']
INFO    -  [16:46:15] Watching paths for changes: 'docs', 'mkdocs.yml', '.'
INFO    -  [16:46:15] Serving on http://127.0.0.1:8000/
  • Previewed documentation at http://localhost:8000.
  • Verified formatting, links, and images render correctly.
  • Checked that all documentation pages appear in the sidebar and all links work.

Closes #4147

@SwapnaliY16 SwapnaliY16 mentioned this pull request Sep 17, 2025
Closed
@ggivo
Copy link
Collaborator

ggivo commented Sep 23, 2025

@SwapnaliY16
Hi, thanks for working on this issue, and sorry for the late response.

I was trying to avoid duplicating the README.md content to avoid supporting the same content twice.
What I was thinking of is using absolute links in README.md to (https://redis.github.io/jedis/), this way will avoid duplicating the content & point to a common place for documentation.

For example ->
[RedisJSON Jedis](docs/redisjson.md)
becomes
[RedisJSON Jedis](https://redis.github.io/jedis/redisjson/)

@SwapnaliY16
Copy link
Contributor Author

SwapnaliY16 commented Sep 23, 2025

Hi @ggivo, thanks for clarifying! That makes sense; using absolute links in README.md to point directly to the GitHub Pages docs would definitely avoid duplication and ensure consistency.

I can update my PR accordingly so that links like [RedisJSON Jedis](docs/redisjson.md) become [RedisJSON Jedis](https://redis.github.io/jedis/redisjson/).

Let me know if you’d prefer me to update the current PR with these changes or open a new one.

@ggivo
Copy link
Collaborator

ggivo commented Sep 23, 2025

Let me know if you’d prefer me to update the current PR with these changes or open a new one.

Updating current one should be fine

@SwapnaliY16
Copy link
Contributor Author

SwapnaliY16 commented Sep 23, 2025

Perfect, thanks for confirming 👍 I’ll update the current PR accordingly.

@SwapnaliY16
Copy link
Contributor Author

SwapnaliY16 commented Sep 25, 2025

Hi @ggivo, I’ve updated the PR to switch the relative links in README.md to absolute links pointing to the published docs, as suggested. Please have a look when you get a chance.

ggivo
ggivo approved these changes Sep 29, 2025
View reviewed changes
Copy link
Collaborator

@ggivo ggivo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@ggivo
Copy link
Collaborator

ggivo commented Sep 29, 2025

@SwapnaliY16

Awesome! Thanks so much for following this through to the end – really appreciate it!

@ggivo ggivo merged commit e838e48 into redis:master Sep 29, 2025
11 of 12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ggivo ggivo ggivo approved these changes

Assignees

No one assigned

Labels

documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Broken links at https://redis.github.io/jedis/

2 participants

@SwapnaliY16 @ggivo