{
  "$type": "site.standard.document",
  "canonicalUrl": "https://johnnyreilly.com/posts/images-in-markdown-for-azure-devops-marketplace",
  "description": "Publish your README/index.md and associated images to Visual Studio Marketplace.",
  "path": "/posts/images-in-markdown-for-azure-devops-marketplace",
  "publishedAt": "2020-11-28T00:00:00.000Z",
  "site": "at://did:plc:yy3apqjlms24kso7ahn7lbmb/site.standard.publication/3mova7c4nho2b",
  "tags": [
    "azure devops"
  ],
  "textContent": "I've recently found myself developing custom pipelines task extensions for Azure DevOps. The extensions being developed end up in the Azure DevOps Marketplace. What you see there when you look at existing extensions is some pretty lovely documentation.\n\n\n\nHow can our tasks look as lovely?\n\nThat, my friends, is the question to answer. Good documentation is key to success. Here's the ask: when a custom task is installed it becomes available in the marketplace, we want it to:\n\n- contain documentation\n- that documentation should support images... For a picture, famously, speaks a thousand words\n\nMark(Down) our manifest\n\nTo get documentation showing up in the marketplace, we need to take a look at the vss-extension.json file which lies at the root of our extension folder. It's a kind of manifest file and is documented here.\n\nTucked away in the docs, you'll find mention of a content property and the words:\n\n> Dictionary of content files that describe your extension to users... Each file is assumed to be in GitHub Flavored Markdown format. The path of each item is the path to the markdown file in the extension. Valid keys: details.\n\nThis means we can have a Markdown file in our repo which documents our task. To stay consistent with most projects, a solid choice is to use the README/index.md that sits in the root of the project to this end.\n\nSo the simple addition of this:\n\nGives us documentation in the marketplace. Yay!\n\nNow the images...\n\nIf we are referencing images in our README/index.md then, as it stands right now, they won't show up in the marketplace. It'll be broken link city. Imagine some Markdown like this:\n\nThis is entirely correct and supported, but won't work by default. This is because these images need to be specified in the files property of the vss-extension.json.\n\nConsider the above; the path of images includes everything inside the images folder in the task. However, it's crucial that the \"addressable\": true is present as well. It's this that makes the files in this path URL-addressable. And without that, the images won't be displayed.\n\nThat's it! We're done! We can have rich, image inclusive, documentation in our custom tasks.\n\nA final note: it's possible to specify individual files rather than whole paths in the files directory and you might want to do that if you're being very careful around file size. There is a maximum size for a custom task and it's easy to breach it. But by and large I find that \"allowlisting\" a single directory is easier.",
  "title": "Visual Studio Marketplace: images in Markdown!"
}