Markdown Documentation Wiki

[krispenner]

It would be incredible if a page in the portal could be designated a wiki and then managed via markdown with child pages. The child pages would not appear in the portal designer - they would just be internal to the wiki which is managed via the parent page in the portal designer. Child markdown pages could be added via git using same directory structure as Azure DevOps wiki does. This would allow a DevOps style markdown wiki for all our documentation which right now is very difficult to publish at a large scale using clunky sections and content components or the REST API. Users really need a better way to host large amounts of documentation inside the developer portal where it belongs along side the API reference.

Similar to question here Option to import static html content into APIM Dev Portal - 1132 but this is a direct request to support a markdown wiki.

Please consider this.

[azaslonov]

Hi @krispenner, yeah I can understand DevOps style approach. Do you think a small script (which you could embed it into your pipeline) that converts markdown documents into our internal format, and pushes them to APIM using REST API could solve your problem?

One disadvantage to this approach - linked resource, i.e. if you want to change the location of a resource, you'll have to manually update hyperlinks everywhere in your markdown docs.

Also, would a special "content writing" mode (i.e. like it is done in https://medium.com/) be better in this case? In this mode, you basically have just the tools required to type the docs into a predefined page template, without having all those widgets handles around.

[krispenner]

Do you think a small script (which you could embed it into your pipeline) that converts markdown documents into our internal format, and pushes them to APIM using REST API could solve your problem?

Trying to convert images and possibly mermaid diagrams which are supported in markdown into the JSON using media components sounds really difficult and kind of backwards. Sure it could be possible but would be very limited without a lot of effort. Markdown is the standard these days for documentation so it should be a supported first class experience in the portal where documentation belongs.

Would a special "content writing" mode (i.e. like it is done in https://medium.com/) be better in this case? In this mode, you basically have just the tools required to type the docs into a predefined page template, without having all those widgets handles around.

We would not go that route, markdown is too portable and really is standard right now for documentation. Having our documentation as markdown will allow for easy importing to other systems later such as if MS publishes a new developer portal in a few years so we avoid re-writing all our documentation again in a new format of theirs.

If you can find a markdown component where you just set a page in the portal designer to be of type wiki, then in the git repo there would be a wiki directory where we just dump md pages and the wiki component would just display those as it's own embedded wiki in the portal. I have not done anything like that before but I imagine there must be JS scripts you can find that just read a directory and display the markdown under a specific parent URL of the site. In my mind it would be easier for you to do something like that which everyone can use than for us to write a script to convert.

Right now, without this support here, we are looking to create a public Azure DevOps team project for just the wiki and host our documentation there with links to it from the API developer portal. We don't have the resources to write a pipeline script and would want to stay with markdown for portability. Eg: dev.azure.com/myorg/apidocs/wiki

[krispenner]

Don't bother with any support for markdown editing in the designer, at least not for now.

I picture user flow like this:

1. User adds new page in the designer and enters the path where the page resides
2. User selects a checkbox or somehow indicates that this page represents a wiki
3. User could indicate wiki name if you were to support multiple wikis, otherwise if not then no name needed
4. User saves and pulls the portal's git repo locally
5. User sees wiki-name directory in the repo or just wiki if multiple wikis are not supported
6. User dumps all their md files and folders in there with resources (images, whatever) exactly like Azure DevOps wiki
7. User commits and pushes
8. User publishes portal
9. User views portal at wiki page path and sees wiki

Again, no need to edit markdown and wiki in the portal designer, if this could work people can just use their preferred local markdown editor (ie VS Code) and push their changes.

[azaslonov]

Technically, we could do export the content back to Markdown as well (losing, of course, all the attributes not supported by Markdown), if the change of the format in the future is your only concern.

Basically, what you describe above defeats the purpose of this project, and probably your best bet would be one of the static website generators.

@mikebudzynski do you have any thoughts on this question?

[mikebudzynski]

@krispenner, could you please confirm my understanding of the problem space, disregarding potential solutions?

1. You would like to use a git repository for publishing the developer portal.
2. You would like to complement fully-customized existing pages with content that's written in markdown (for example, API tutorials).
3. You would like to edit the markdown pages in the admin mode of the portal in a markdown text editor, without placing any other widgets.
4. You would like to edit markdown files locally in the markdown format, without the current JSON structure.
5. You would like to store and source control markdown files in a git repo, without the current JSON structure.

[AnRei123]

We currently phase the problem that we think about migrating different mark down pages and structures from different Azure wikis to the Developer Portal. Currently, these markdown pages are maintained directly by the dev teams which is more scalable than if I would need to centrally maintain and update the content from the portal in editor mode.
On the one hand it would be great if the markdown would be still accessible to the teams for a decentralized update option for the teams via the Azure wikis. On the other hand, I would need to control which updates and contents are exposed to our external partners.
From the developer experience point of view, the markdown content and structure might need to be displayed as a deeper sub section in the portal. So, we might need a hybrid approach. And, for me it is important to have source control and control about which contents are deployed in which status to other environments.
So it seems that our use case would be slightly different. For us, it might be worth to think about being able to upload wiki pages and structures in markdown format as a kind of media object. It should be possible to edit the markdown data either directly via the editor mode of the portal or from the downloaded media sub folders that include all the md files.
This approach might allow us with the help of our APIM Azure repository - where we centrally store the downloaded json and the media files before deploying them to other managed portal environments - to allow dedicated updates of markdown files in the Azure repository before we deploy the changes.
Remark: By the way, with the help of scripts, for some portal environments, we slightly change the json file and adapt it before deploying it to a dev or a production environment as some contents should be only visible to our internal developers and some contents should be only visible to our business partners. The same might apply also for markdown pages. Some might be for developers only and some might be also intended for our business partners. Therefore, it is very important that we have a hybrid approach in place that allows us to still control all the data and to adapt it to our needs when deploying it to the different environments.

[krispenner]

@azaslonov

what you describe above defeats the purpose of this project

Can you elaborate on what the defined purpose of this project is? I'm sure there is much more than what I need it for, but I had assumed the primary focus was to list all of the available APIs to our customers, allow them to sign-up with a developer account, subscribe to the APIs, and then test them directly in the portal. While you are continually improving on these features, I never really understood the reason/benefit for all the widgets, sections and custom pages - we don't use them ourselves much. I wouldn't expect people would use this as their marketing or company web site which they need to update content on all the time. To me the next logical step is to incorporate API documentation into the portal so it can sit along side the APIs and be secured via the developer account login the portal provides. So using an external static website generator does not work nearly as well as incorporating right into the portal itself.

@mikebudzynski
Mike, all your points apply, however your point 2 is ultimately my primary request:

2. You would like to complement fully-customized existing pages with content that's written in markdown (for example, API tutorials).

Absolutely. Without using sections, widgets, JSON structure, REST integration etc. A dedicated documentation wiki I think would be easiest, because if we have 100 pages of documentation to upload, we don't want to add each individual page to the portal, the current UI would not scale nicely for that kind of volume in my opinion.

Interestingly I forgot the new portal dropped support for git and I even asked about this over a year ago, so this definitely complicates my request now. So to your points you asked about, the rest involve git in some way and obviously this is no longer a trivial ask since you don't support git anymore. The old deprecated portal supported git, which was a very powerful feature btw, and I forgot that when I raised this new issue.

[azaslonov]

That is very interesting feedback folks, I honestly haven't thought from that angle. I feel like we need a deeper and probably in-person conversation on these tocips.

@krispenner, your definition of the purpose matches mine precisely. Answering your question: the widgets and the whole styling system here are to help the majority of customers to reflect their brand while publishing the API documentation, and with Markdown alone, it is hard to do so without getting into coding with all the outcomes, from my point of view not everybody ready to jump into it.

We didn't drop Git btw, we just not yet added the support for it, and honestly, there were not many people asking for it, but looking at the conversation above I see that it is very much relevant.

@AnRei123, @krispenner, I would love to look close into this hybrid approach. To me, having the markdown authored separately, in separate tools, and then "assigning" it to particular pieces of content (or a layout) rather than having everything in one place/tool, looks like creating additional work for yourself, and yet, you're ready to do it. This part I would like to better understand. For instance, what do you think is missing for you to switch to this single tool? Earlier I mentioned a special "content writing" mode above, plus maybe the ability to export content as Markdown any time, would that allow you to switch? Maybe something else?

[krispenner]

Earlier I mentioned a special "content writing" mode above ... would that allow you to switch?

Probably not, unless it came with a 100% confirmation that you would also add support shortly after for Git so we can manage the documentation externally. We would like to avoid all our developers going into the portal editor/designer to edit this documentation. It needs to be imported as markdown - hence why git makes the most sense.

Allow me to describe a few more ideas and our bigger picture - this may not provide any answers but just some additional thoughts to consider.

Similar to @AnRei123 we also have all our internal API documentation written by our developers in our Azure DevOps wiki - internal integrations use this documentation. We are in the process of re-writing the pages in a separate customer focused wiki that removes internal references and notes that are not applicable for our customers. So we also have internal vs external documentation. Right now, we use Print-to-PDF to print the documentation pages as needed to hand out to our customers - this is not a scalable solution.

For deployments, our Azure pipelines use PowerShell scripts to create/update the version sets, APIs, products and security groups in our API Management instance per environment and then uploads the OpenAPI 3.0 JSON file to the API.

So some thoughts to consider - these are not requests just thinking out loud here:

1. At the most basic level, having the ability to add documentation pages per API would allow to provide better documentation for each API. The markdown documentation would be some how linked to and referenced by that API.
2. Could documentation per API be it's own entity in the API management namespace and be deployed as part of our pipeline per API? The markdown pages could be stored along side the API code itself if wanted. Similar to uploading the OpenAPI 3.0 JSON spec file we also would upload one or more markdown pages (single md file, folder, or zip file) for the documentation of that API, eg:
   1. Import-AzApiManagementApi -ApiId "MyApi" -SpecificationFormat "OpenApi" -SpecificationPath "/swagger.json"
   2. Import-AzApiManagementApiDocumentation -ApiId "MyApi" -DocumentationFormat "Markdown" -DocumentationPath "/docs"
3. Ability to hide contents in the documentation based on the user's security group such as internal staff vs external customer. It would allow us to maybe keep one instance of the documentation instead of two nearly identical copies.
4. Ability to integrate and point the documentation to an Azure DevOps wiki instance and root path so editing remains in DevOps where the developers have better access and the API developer portal just displays it.

I actually think that:
Import-AzApiManagementApiDocumentation -ApiId "MyApi" -DocumentationFormat "Markdown" -DocumentationPath "/docs"
could be really useful and powerful, I only just thought about it so not flushed out and maybe not practical.