Styling readme.html in plugin?

1 Views

I am making readme.html file for a plugin with some detailed setup instruction that need to include screenshots.

As rest of UI I want it be consistent with WordPress style and so I looked at its own readme.html.

Read More

It includes stylesheet with relative path: 

<link rel="stylesheet" href="wp-admin/css/install.css?ver=20100228" type="text/css" />

So for a plugin file I might go with: 

<link rel="stylesheet" href="/wp-admin/css/install.css" type="text/css" />

But it is good way to include styling? There are really many ways to do it:

  • link to install.css;
  • bundle copy of install.css with plugin;
  • bundle own CSS file with plugin;
  • embed style in readme.html.

I am not aware of any recommendation about providing HTML documentation with plugins.

Had you included HTML documentation with plugins (or themes, whatever)? What method had you chosen to style it and what was you reasoning for it?

Post Views: 1

Related posts

Leave a Reply

3 comments

  1. It would be better to include your own CSS file that way you can:

    • Use a relative path to your CSS.
    • Avoid problems getting the path right to the wp-admin directory. Not all people put WordPress in the root directory, so your example above would break for them.
    • Possibly redundancy by reusing the CSS in your HTML & admin pages for your plugin.

  2. I suggest you take a look at Justin Tadlock’s Get the Image plugin. He includes readme.html, readme.txt, and readme.css.

    Regarding the path to your css file, what you posted wouldn’t make sense (I don’t think). I’d suggest something like 

    <link rel="stylesheet" href="readme.css" type="text/css />

    and just put readme.css in the same directory as your readme.html file.

  3. I can’t think why you’d bundle a stylesheet alongside a readme, it’s viewed independantly from anything else, so why not just put that same CSS in the HTML file(seeing as you’re going to have to maintain it anyway).

    <style type="text/css">
/* 
.example { }
*/
</style>

    Using inline styles:

    Pros

    • One less HTTP request
    • No extra files to manage
    • No need to worry about any path problems

    Cons

    • No included stylesheet(you’ll have to maintain your CSS inline with the WP install.css)
    • All styling will have to be managed(and maintained) inside the readme document *¹

    *¹ – Not really a big deal, the CSS will be right near the top of the file.

    What i’d actually do though is just use an external source, that will update inline with WordPress, and you’ll avoid any pathing issues(because the external path should always be valid).

    Maybe use WordPress.com as the source?

    <link rel="stylesheet" type="text/css" href="http://s%NUM%.wp.com/wp-admin/css/install.css" />

    Where %NUM% would be a numeric value(eg. 1 or 5, and so on..) to represent which server you want to pull the CSS from. I tested upto s20.wp.com, not sure how high they go.

    That way you at least know a few users will have it cached already.

    You could also use the WordPress.org svn or any number of other places that serve up WordPress CSS, i just figured WordPress.com blogs are popular and more likely to be cached.