What's the best way to include user documenation with your plugin?
Answered
In the plugin.xml file for a plugin, there's a description section like this:
<description><![CDATA[
My <b>awesome</b> plugin
]]></description>
I've seen a few examples of plugins that use this description tag for user documentation and examples, but mostly I see short descriptions, maybe with a few bullet lists.
The HTML rendering for anything complex is typically ugly. I don't see anyway to specify a style sheet, and my attempts at embedding CSS in my HTML via style attributes are simply ignored.
Is the typical way to handle documentation to simply put anything particularly detailed on the plugin's homepage?
Can I use Markdown for that, or should I use HTML?
How would I preview my documentation before publishing my plugin?
Please sign in to leave a comment.
Providing documentation in the plugin's description is not the best idea in my opinion - as you've noticed, HTML support may be limited, especially when rendered inside the IDE Preferences > Plugins.
On the top of the description, you can create links to the proper documentation pages, which would be more attractive to the user that a huge block of text.
As a docs page, you can use GitHub README or Custom Pages for your plugin in the Marketplace - both accept Markdown and provide a preview.
I've already created a GitHub README and added a link to it in my description. These "Custom Pages" in the Marketplace that you mention are perhaps what I was wondering about.
I haven't found any docs yet on how to do create such pages, but for now I suppose I'll settle for the link to my README, publish my plugin, and see if making a Custom Page becomes clear later.
Just go to your plugin details page on Marketplace when logged in - there should be another Custom Pages tab available next to the Overview, Versions, Review.
What threw me off was that I was hoping to have everything all set to go before I created a new Marketplace page, rather than creating the page first, and only then being able to add a documentation page after.
The only other plugin I've published so far was a VSCode extension. That appeared and became available the moment I published it, with my existing README appearing directly on the Marketplace page automatically.
But since the way it works for IntelliJ only means a small delay in having documentation in the Marketplace, it's no biggie, just different that I was expecting.
Thanks, Kerry. I'll let the MarketPlace team know about that!