search

thunderstore-io / Thunderstore

Thunderstore is a mod database and API for downloading mods. Thunderstore Discord: https://discord.thunderstore.io/
https://thunderstore.io/
GNU Affero General Public License v3.0
128 stars 27 forks source link

Add asciidoc readme support #971

Open Xenira opened 8 months ago

Xenira commented 8 months ago

My mod repo uses a README.adoc instead of a markdown file.

My current solution is to convert it to markdown before upload. It would be great to have the ability to use asciidoc, this would eliminate that extra step for publishing and the loss of features, that conversion to a less powerful format entails.

MythicManiac commented 8 months ago

Hey, I'd say this is unlikely to happen (I'll explain why in a bit) but I'll keep the issue open regardless as it is a valid feature request & perhaps it'll become possible in the future.

As for why this is unlikely to happen, the current design philosophy around the package format and other metadata is to keep everything as easy to consume as possible. The thinking is that the more complexity we introduce to the package format, the higher the burden is for 3rd party developers to implement tooling for handling the packages correctly. In this case, if we were to allow asciidoc formatted documents, every current & future piece of software that wants to properly render the readme also has to add that support.

There is a potential way around this problem, which would be for us to provide a robust library for performing this specific task. If we were to do that, it'd delegate the responsibility of maintaining compatibility with new features from the 3rd party developer(s) to us. That said, I don't foresee this kind of tooling being available in the near future yet.

Something we perhaps could look into is adding support for auto-converting asciidoc to markdown as a pre-processing step once we have a proper pre-submission-draft state for uploads supported (while I don't have a timeline for it, it is required for a handful of other feature we'd like to also implement).

Xenira commented 8 months ago

Thank you for your thorough explanation. I completely agree, that 3rd party developers need a simple and standardized package format and adding asciidoc would ad unnecessary complexity.

One possible solution I would like to propose would be to create an API endpoint for the rendered version of the readme. The upside would be total freedom regarding readme format and possible supported format extensions while removing the need for 3rd party tools to include a renderer themselves. On the other hand it does nothing if those tools want to allow the same control over how the readme is rendered. Ultimately, I am not entirely sure if this would be a viable way, as I don't know the current ecosystem and their requirements well enough.

MythicManiac commented 8 months ago

Hey, we already have an API for rendering actually, but we're also trying to maintain offline compatibility for client software so we can't exactly rely on it for rendering needs for use cases other than the website.

If we get around to standardizing a rendering library which the clients can rely on as well, we'd probably take that one into use on the website/API as well to keep everything as consistent as possible.