{"id":4314,"date":"2017-11-25T08:15:06","date_gmt":"2017-11-25T07:15:06","guid":{"rendered":"https:\/\/florianbrinkmann.com\/en\/?p=4314"},"modified":"2020-02-09T10:59:41","modified_gmt":"2020-02-09T09:59:41","slug":"convert-wordpress-plugin-readme-to-markdown","status":"publish","type":"post","link":"https:\/\/florianbrinkmann.com\/en\/convert-wordpress-plugin-readme-to-markdown-4314\/","title":{"rendered":"Convert WordPress plugin readme to Markdown"},"content":{"rendered":"<p class=\"wp-block-paragraph\">The <code class=\"lang-markup\">readme.txt<\/code> of a WordPress plugin needs to be formatted in a specific way, as shown in the <a href=\"https:\/\/wordpress.org\/plugins\/files\/2017\/03\/readme.txt\">example readme<\/a>. Parts of that are already Markdown formatting, but, for example, the headlines are formatted differently. In this post, I show you a tool which converts the WordPress readme format into valid Markdown.<\/p>\n\n\n\n<!--more-->\n\n\n\n<p class=\"wp-block-paragraph\">If I copy the <code class=\"lang-markup\">readme.txt<\/code> content into a <code class=\"lang-markup\">readme.md<\/code>, it looks like it could be optimized a bit (the screenshot is from GitHub):<\/p>\n\n\n\n<figure class=\"wp-block-image alignnone size-full wp-image-4316\"><noscript><img decoding=\"async\" width=\"994\" height=\"504\" src=\"https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown.png\" alt class=\"wp-image-4316\" srcset=\"https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown.png 994w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-394x200.png 394w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-300x152.png 300w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-768x389.png 768w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-806x409.png 806w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-600x304.png 600w\" sizes=\"(max-width: 994px) 100vw, 994px\"><\/noscript><img decoding=\"async\" width=\"994\" height=\"504\" src=\"data:image\/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20994%20504%22%3E%3C%2Fsvg%3E\" alt class=\"wp-image-4316 lazyload\" srcset=\"data:image\/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20994%20504%22%3E%3C%2Fsvg%3E 994w\" sizes=\"(max-width: 994px) 100vw, 994px\" data-srcset=\"https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown.png 994w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-394x200.png 394w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-300x152.png 300w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-768x389.png 768w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-806x409.png 806w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-600x304.png 600w\" data-src=\"https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown.png\"><figcaption>The readme.txt format of WordPress in a Markdown file. (Screenshot: GitHub)<\/figcaption><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">The headlines are not highlighted, and the plugin headers are in one line (okay, the latter could be fixed by just adding two spaces after each header).<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Luckily, there is a project called <a href=\"https:\/\/github.com\/wpreadme2markdown\/wp-readme-to-markdown\">WP Readme to Markdown<\/a> \u2013 a converter that correctly formats the headlines, plugin headers, and inserts screenshots. There is also a <a href=\"https:\/\/github.com\/wpreadme2markdown\/wp2md\">CLI version<\/a>, that can be run after changing the <code class=\"lang-markup\">readme.txt<\/code> easily \u2013 theoretically automatic of course, for example via an NPM script with watcher plugin.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">But I did not want to through NPM or similar on my plugin, just to get this ability, so I run the command by hand. After installing the CLI via Composer, you go the to <code class=\"lang-bash\">vendor\/bin<\/code> directory in the console and run the following command:<\/p>\n\n\n<pre class=\"wp-block-code lang-bash\"><span><code class=\"hljs\">wp2md -i ..\/..\/readme.txt -o ..\/..\/README.md<\/code><\/span><\/pre>\n\n\n<p class=\"wp-block-paragraph\">That converts the <code class=\"lang-markup\">readme.txt<\/code> from the root directory of the project into a <code class=\"lang-markup\">README.md<\/code>. The result looks like that:<\/p>\n\n\n\n<figure class=\"wp-block-image alignnone size-full wp-image-4315\"><noscript><img decoding=\"async\" width=\"993\" height=\"688\" src=\"https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-after-conversion.png\" alt class=\"wp-image-4315\" srcset=\"https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-after-conversion.png 993w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-after-conversion-289x200.png 289w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-after-conversion-300x208.png 300w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-after-conversion-768x532.png 768w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-after-conversion-806x558.png 806w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-after-conversion-600x416.png 600w\" sizes=\"(max-width: 993px) 100vw, 993px\"><\/noscript><img decoding=\"async\" width=\"993\" height=\"688\" src=\"data:image\/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20993%20688%22%3E%3C%2Fsvg%3E\" alt class=\"wp-image-4315 lazyload\" srcset=\"data:image\/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20993%20688%22%3E%3C%2Fsvg%3E 993w\" sizes=\"(max-width: 993px) 100vw, 993px\" data-srcset=\"https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-after-conversion.png 993w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-after-conversion-289x200.png 289w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-after-conversion-300x208.png 300w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-after-conversion-768x532.png 768w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-after-conversion-806x558.png 806w, https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-after-conversion-600x416.png 600w\" data-src=\"https:\/\/florianbrinkmann.com\/en\/wp-content\/uploads\/sites\/11\/2017\/11\/wordpress-plugin-readme-txt-format-in-markdown-after-conversion.png\"><figcaption>Nicely formatted: the Markdown file with the converted content of a WordPress readme. (Screenshot: GitHub)<\/figcaption><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">If someone has an idea, how to get this automated with nothing but Composer and Git, let me know \ud83d\ude42<\/p>\n","protected":false},"excerpt":{"rendered":"<p>The readme.txt of a WordPress plugin needs to be formatted in a specific way, as shown in the example readme. Parts of that are already Markdown formatting, but, for example, the headlines are formatted differently. In this post, I show you a tool which converts the WordPress readme format into valid Markdown.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"wpf_show_in_dewp_planet_feed":false,"flobn_post_versions":"","webmentions_disabled_pings":false,"webmentions_disabled":false,"lazy_load_responsive_images_disabled":false,"footnotes":""},"categories":[37],"tags":[],"class_list":["post-4314","post","type-post","status-publish","format-standard","hentry","category-wordpress"],"wp-worthy-pixel":{"ignored":false,"public":null,"server":null,"url":null},"wp-worthy-type":"normal","_links":{"self":[{"href":"https:\/\/florianbrinkmann.com\/en\/wp-json\/wp\/v2\/posts\/4314","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/florianbrinkmann.com\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/florianbrinkmann.com\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/florianbrinkmann.com\/en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/florianbrinkmann.com\/en\/wp-json\/wp\/v2\/comments?post=4314"}],"version-history":[{"count":3,"href":"https:\/\/florianbrinkmann.com\/en\/wp-json\/wp\/v2\/posts\/4314\/revisions"}],"predecessor-version":[{"id":5831,"href":"https:\/\/florianbrinkmann.com\/en\/wp-json\/wp\/v2\/posts\/4314\/revisions\/5831"}],"wp:attachment":[{"href":"https:\/\/florianbrinkmann.com\/en\/wp-json\/wp\/v2\/media?parent=4314"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/florianbrinkmann.com\/en\/wp-json\/wp\/v2\/categories?post=4314"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/florianbrinkmann.com\/en\/wp-json\/wp\/v2\/tags?post=4314"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}