Allow README.md to optionally render as the project page

I thought about this today when I had to manually edit the description of a module to just re-create what was already written in markdown but in HTML.

It really feels outdated and backwards. Anything, from Github/Gitlab to almost every modern tool is able to read and parse a README.md file to create a welcoming page for projects.

Also, this encourages developers to create a single point for basic documentation and info instead of having several, often outdated and/or conflicting sources.

Surprised to see that this post is 11 years old...

For what is worth, +1 to having this. I guess tooling has evolved during these 11 years and standards on markdown have settled, so I think this could be re-considered.

Unrelated to drupal.org, but I would also happily extend this and make the hook_help() also read from the markdown file. I don't get what's the use of having three different sources of info (the README.md, the hook_help, the project description) that usually need to tell the same information: what's the project, how to use, how to install, requirements.

UI-wise, we could have a button that tries to fetch the contents and overwrites whatever is in the description (transforming markdown to html), all ajax driven.

That way we make it a one-off fetch operation and give the user the possibility to refresh when editing and we would not need an additional field on projects or do constant external requests.

Suggestion:

Yep, @flgarlin proposal ✨ Allow README.md to optionally render as the project page Fixed could be a good solution and probably easier to get done.

I still think on the long run Drupal modules should move towards a single source for module documentation (and that single source should be fetched from elsewhere: drupal.org, hook_help, etc), but that's another discussion.

I'll work on it.

Yay, excited to see this moving forward!

In general, I'm all in favor of a single, canonical copy of something, instead of duplicate, out of sync versions. However, for something like a README.md file, the requirements, instructions, functionality, etc, might change across different branches. So long as it's a README.md file in Git, it all works great, and you can easily maintain the differences as needs change. But for a d.o (or any other) project page, you might need different information that's true across all branches.

The solution @fjgarlin came up with of an AJAX-driven import where you select a specific branch seems like a great compromise. If a project is simple, and everything can be said exactly once, yay. If it's complicated and needs different instructions in different branches, it can either not use this feature at all, or start with an import, then customize the results to be more general...

Sounds like this is no longer postponed, so removing the "[PP-3]" from the title.

Thanks again,
-Derek

This is ready to review.

See code changes here: https://git.drupalcode.org/project/drupalorg/-/merge_requests/157

Here is a demo to see how it looks and how it works: https://www.drupal.org/files/issues/2023-02-21/Screen%20Recording%202023... →

Happy to address any feedback.

Feedback: As i read #80, this is about a button to copy a readme of some arbitrary branch to the description.

Sorry, but i can not see that this addresses the need addressed in the issue.
As a module maintainer i want to
- be "DRY" and not maintain a text in different locations, and most important, toolsets.
- to update stay in my toolset of code editor and git.

Stated differently, if i'm updating a module, i have it open in my IDE anyway. If i have to open drupal.org, copying the text from my IDE is simpler that hitting a button, and in the end i know it's the correct version.

As i understand this issue:
As a module maintainer, i want to update the project page by pushing updated file(s).

Agreed with #87.

Given that gitlab supports this out of the box, and that d.o is moving to use gitlab for project management, should this be closed as a "won't fix"?

(I did not read the whole discussion, just the IS, but) What about this:

As a module maintainer, i can put [tokens] into the description text that embed a project file (spcedified in the token from a branch specified in the token) as rendered HTML.

We can bikeshed about the details, but tha would address my need as multi-maintainer. E.g. if i want, i can add readme files of different branches, and wrap them in details tags.

That would work for me.

#88:
> and that d.o is moving to use gitlab for project management, should this be closed as a "won't fix"?

This depends if gitlab will be the main project frontend.
(Btw, there is an analogous issue for the description text of gitlab projects, the text that is displayed in project lists.)

d.o is moving to use gitlab for project management

Even tho many things are moving to gitlab (issues, CI...), there are many other parts of d.o projects that won't. Project pages will stay in d.o in the foreseable future.

As discussed in earlier comments, not everybody might actually want to pull the info from readme files into the description (for different reasons), so this additional just gives them the possibility of a "quick" copy/paste into the body field.

My only concern with the tokens would be the performance as we'd need to make external requests to bring that in.

#89 could be good for me - or just links to the rendered readme at Gitlab.

However, to me the real problem is that the project pages often contain too much information. As already mentioned, we have doc guides and readmes for projects. The project page shouldn't repeat this (unless it's automatically maintained for example with tokens as suggest above in #89).

One idea: We already select a default branch. Used that information to select readme that is automatically added to the project page.

> My only concern with the tokens would be the performance as we'd need to make external requests to bring that in when displaying the project.

Page cache and/or caching in the token provider should be relatively simple. Invalidating on every commit also, as we have the build logic on commit anyway (and maybe we have cache tags by then ;-).

@fjgarlin: Amazing, thanks! Fantastic progress. 🎉

@everyone who thinks this is totally insufficient and wants something else: Please remember that d.o can be a slow moving site, change can be hard, and when someone makes a solution that helps (but doesn't totally solve) your use case, and still supports other people's use cases, I recommend leading with gratitude and appreciation, not complaints that it's not good enough. 😉

If comparing this to Gitlab, keep in mind that the UI works there since the "project home page" is itself a Git filesystem browser, including a branch filter with a pre-selected value, and a list of files/directories in the root of the repo. Not everyone browsing / using the project page necessarily wants/needs to interact with it as a Git repo, wants to see the codebase of that project (if any), or even understands branches and how to pick one. Yes, we can specify a default branch in the d.o project, so we could use that, but not every project page can always === the contents of the README.md on the default branch. Some projects have no code, and potentially no Git repo at all.

If we're going to automagically slurp in the README.md from the default branch on every commit to that branch or something, and cache that in the d.o DB, I'd vote we stick that into a separate field from the project body, and give maintainers the choice to show either the README, body, or both (but not neither 😅).

And, I think this is already great progress, could probably be committed and deployed ASAP, and we can open follow-ups to explore further improvements / changes. I just haven't looked at any of the code, so I can't RTBC this.

Thanks again,
-Derek

Thanks for the feedback. I'll try to work on those things soon.

Addressed some of the feedback and followed up with some questions on some of the comments.

The latest round of feedback has been addressed.

Adding a quick demo video to see how messages display, showing that the escaping is correct, etc: [ video → ]

Looks fantastic, many thanks!

Great work @fjgarlin, it's nice to see this getting very close to being a reality.

This has been merged & deployed!

Automatically closed - issue fixed for 2 weeks with no activity.