Use readme.md as fallback

[renathoc]

Our plugin directory uses the readme.txt file, with custom markdown support, to show our plugin description. And usually, we create readme.md for our repos. For this reason, we need to create 2 readme for our projects.

I think it would be good to have the readme.md support (rendering markdown like the main repos: github, gitlab, bitbucket) for the Plugin Directory. To keep the backward compatibility, we could use the readme.md as a fallback when we don't have the reame.txt

Reference: ​https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/

[Otto42]

This is already done. If readme.txt is missing, then it will use the readme.md instead.

However, note that the formatting requirements are unchanged, the md file will be parsed exactly the same as the txt file.

[SergeyBiryukov]

Duplicate of #403.

[dufresnesteven]

If the code behaves this way, it should be documented for the end user.

The lack of documentation is why this ticket was opened in the first place.

Should we update this ticket to address the documentation issue as opposed to close it?

[SergeyBiryukov]

Some context from comment:7:ticket:403:

Note that the format for both files is identical. If the readme.md exists, and readme.txt does not, then the readme.md will be used. Additionally, the readme.md is renamed to readme.txt before the official ZIP is built and released to sites.

There are no plans to support GitHub flavored markdown. For this reason, we continue to recommend using the name "readme.txt" and not "readme.md", as they are unlikely to be of the same format. Additionally, GitHub uses the readme.md for entirely different purposes than the plugin directory does.

Re: "the readme.md is renamed to readme.txt before the official ZIP is built", it doesn't look like that's still the case after the Plugin Directory overhaul in #1584, could not find any code for that at a glance.

We could probably add a note along the lines of the comment above (that readme.md is supported but not recommended, and readme.txt is preferred) to these pages:

• ​https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/
• ​https://developer.wordpress.org/plugins/wordpress-org/plugin-assets/

[dufresnesteven]

Aha! I see the predicament.

If we won't support Github markdown in the immediate future, maybe its best to let the move through quietly for now then.

I appreciate the extra info!

Replying to SergeyBiryukov:

Some context from comment:7:ticket:403:

Note that the format for both files is identical. If the readme.md exists, and readme.txt does not, then the readme.md will be used. Additionally, the readme.md is renamed to readme.txt before the official ZIP is built and released to sites.

There are no plans to support GitHub flavored markdown. For this reason, we continue to recommend using the name "readme.txt" and not "readme.md", as they are unlikely to be of the same format. Additionally, GitHub uses the readme.md for entirely different purposes than the plugin directory does.

Re: "the readme.md is renamed to readme.txt before the official ZIP is built", it doesn't look like that's still the case after the Plugin Directory overhaul in #1584, could not find any code for that at a glance.

We could probably add a note along the lines of the comment above (that readme.md is supported but not recommended, and readme.txt is preferred) to these pages:

• ​https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/
• ​https://developer.wordpress.org/plugins/wordpress-org/plugin-assets/