Link to the rendered readme on GitHub

[FichteFoll]

Instead of linking to the raw readme, we should link to the rendered one on Github.

[braver]

Good point, didn't even look at that yet. The thing is that we only have a path to the raw README in the workspace.json. E.g. https://raw.githubusercontent.com/fraoustin/Sublime2pdf/master/README.md. I guess we can try to rewrite that to rendered one (e.g. https://github.com/fraoustin/Sublime2pdf/blob/master/README.md ➡ change the domain and add /blob between the repo and the branch)... Just not sure how reliable it is to do that in post processing. Perhaps @kaste can we get the readme link we need from the crawler?

[kaste]

Which readme link to do you mean. The README is basically the landing page? Which one of the links do you mean?

https://raw.githubusercontent.com/timbrel/GitSavvy/master/README.md
https://github.com/timbrel/GitSavvy
https://github.com/timbrel/GitSavvy/blob/master/README.md

Why don't you render the README markdown. Fetch it, process it, and render. Dynamically of course.

[kaste]

Ok, I now see what link you want. Why is that better? Anyhow, we construct the readme link for each hub. E.g.

async def find_readme_url(session, owner, repo, branch) -> Url | None:
    """
    Fetch the root directory file listing and return the raw URL of the README if found.
    """
    files_url = f"{BITBUCKET_API_URL}/repositories/{owner}/{repo}/src/{branch}/?max_depth=1"
    files_data = await fetch_json(session, files_url)
    entries = files_data.get("values", [])
    for entry in entries:
        if entry.get("type") == "commit_file" and entry["path"].lower() in _readme_filenames:
            return f"https://bitbucket.org/{owner}/{repo}/raw/{branch}/{entry['path']}"
    return None

T.i. we don't "just" get them, we construct them. For each of the three repos, we would need a transformer for the URL. However, I think you should just render this on the fly. Just from the names and descriptions of the packages you can't really make any comparison.

[braver]

The reason I don’t render it is because rendering markdown is in itself easy, but doing it in a way that is completely compatible with how the readme appears in GitHub, including handling all sorts of images (and where they might actually be hosted), is not. A lot of readmes that look great on GitHub are broken on packagecontrol.io. I just don’t want to go down that rabbit hole.

That’s the technical and practical side. I also don’t want this site to start acting like the homepage of the package. That should be the GitHub repo and we should lead people there instead of trying to “capture that traffic”. If people need any info, the sooner they land on the repo and are able to interact with the repo and the maintainers, the better.

Now for browsing color schemes for instance I get the use case of immediately seeing the images etc. But the images are the surprisingly non-trivial element here.

Example: https://packagecontrol.io/packages/Theme%20-%20Rose%20Pine
Note the missing logo (it just prints the alt text).

[braver]

Why is that better?

Deeplinks to headings, clickable links, images. Now all you get is raw markdown.
Of course we do also link to the repo homepage… that’s almost always as useful as the readme.

I’ll have a look at what can be done to link to a rendered readme more easily. If I ever get super bored I might even look into rendering it an figuring out the pitfalls. Anyone else is of course also totally welcome to try 😊

[braver]

Or perhaps I’m just taking too much of a perfectionist approach. I can’t help being annoyed by broken images. Perhaps we could put some caveats around it and render a “no guarantees preview of the readme” using marked, a sanitizer, and something to help fix paths…

[kaste]

Then maybe, keep it more simple. Why every package has a landing page? Just make the card bigger, and show the most recent version, and the links. What do we have on the package details site?

For the themes, schemes, we should probably have a fancy ST command that just temp downloads them and previews them in the editor. T.i. for anything else that is not a theme or scheme, the readme might give a hint about the functionality.

EDIT: the big README rendering on GitHub looks really nice actually.

[braver]

What do we have on the package details site?

Several things that are relevant:

• creation date
• a list of (sometimes several) releases for platforms and st version ranges
• a donation link
• a homepage link that’s not the repo

We can’t fit that all in the listing while keeping the listing usable. And the detail page can grow over time as we add statistics or other features.

[kaste]

Just make the card bigger

Yeah, we have 12 small cards, and on click you zoom the card.

[braver]

Oh yeah I considered that, but I like having a URL you can simply go to. I like how the internet used to work with links and pages and a back button (I only break that here a bit because I’m a bit outside my “zone” here).

And also, that’s not MVP or anything I actually have time for 😅

[kaste]

Package Control R                          [ Search...    ]
-----------------------------------------------------------

# New                              # Just updated

* Fokka #ST4 #W                    GitSavvy 1.51.4
* Moouche Starr                    LSP  2.45.2








Package Control R                          [ lint         ]
-----------------------------------------------------------

SublimeLinter  by *SublimeLinter*                   28 stars
LSP  by *LSP*                                       41 stars
...









Package Control R                          [ lint         ]
-----------------------------------------------------------

SublimeLinter  by *SublimeLinter*                   28 stars
The code linting framework for Sublime Text

3.42.2 #ST4   /   2.51.0 #ST3
2025-04-26        2016-08-12

[REPO]  [README]  [DONATE]





LSP  by *LSP*                                       41 stars
...

[kaste]

Okay, the permalink. But this issue here was about not rendering but only linking to the README documentation, and then the permalink has almost nothing to show, and then me thinks, just condense it. You still had the permalink as another link [REPO] [PERMA]. PERMA being just an icon.

I like how the internet used to work

I'm older than you, the internet was text based. And before Netscape it was crazy.

[braver]

I don’t see what that solves though? Sure on 27” there’s a lot of white on the detail page, but we might still eventually put the readme in there. Or a download stats chart, etc. Moving the details into the results view makes doing new things in the future harder.

And before Netscape it was crazy.

I’m not that young that I don’t remember that 😉 But sure! You got my point though 😊

Anyway, I don’t disagree with the idea right away, I just don’t really know how to make that work and it’s not the most important thing right now. In other words, it hasn’t tickled my brain in a way that makes me try and code it up 😅