Azure-devops-docs: I've got warning sings on folders with no markdown files

[DanJ210]

I've used my repo to create a wiki and I thought that the folders which didn't have markdown files would not show up. All folders are showing up including the .vscode folder. There's nothing weird in them except JSON files so I'm not sure why they would error. I've created markdown files for them just to see what happens and still I've got the warning. I don't believe a .order file would help me here as it's only for ordering. How would I exclude folders from showing up? Or fix warnings without there being an apparent issue?

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 172eecd7-1a6b-30d0-96c0-fa6ae56b521c
• Version Independent ID: adc2c741-a41f-68d9-cdaf-dac696e68b9f
• Content: Clone and update wiki content offline - Azure DevOps
• Content Source: docs/project/wiki/wiki-update-offline.md
• Product: devops
• GitHub Login: @chcomley
• Microsoft Alias: chcomley

[chcomley]

Hi @DanJ210, I've engaged our PM, so stay tuned! I'm sorry for any confusion. Thanks for reaching out.

[DanJ210]

Ok no problem. Maybe I'm misunderstanding some but from I got from the docs is that folders wouldn't show up without a related markdown .md file. Just adding this to the above.

[adramasu]

hi @DanJ210, we don't check the presence of markdown files inside a hierarchy when a publishing code as wiki. This will be a very costly task as we would then end up scanning through all the folders and subfolders (upto the leaf node) to check for the presence of the Markdown file. This would affect the performance significantly. We don't want to compromise on the performance. Please let us know if this turns out to be a blocker for you.

[adramasu]

Also the warning signs are for folders which don't abide by the naming conventions of a Wiki file/folder.

[JoeSchmeltzer]

@adramasu, I was under the same impression as @DanJ210 that folders without .md files wouldn't show up in the wiki. I thought that was the case because of this documentation: https://docs.microsoft.com/en-us/azure/devops/project/wiki/publish-repo-to-wiki?view=azure-devops#publish-a-git-repository-to-a-wiki-1

Here's the line from the article:
"Choose Publish. The wiki repo is populated with the Markdown files and folders included within the repo you selected. If a sub-folder does not contain a Markdown file, it doesn't appear in the Wiki."

Trying to start a wiki from my code that shows every single folder is pretty unusable. It is impossible to find where the actual documentation is. If that's the case, I might as well just keep my wiki separate from my code. I was hoping that the "publish wiki from code" option would detect where I have .md files and display them in a hierarchy that matches our code repository. Then as we add .md files, they would start to show up in the wiki. Is that not correct? Is there something I'm missing here? Thanks.

[adramasu]

Hi @JoeSchmeltzer, your ask is very valid. The only reason that we didn't autohide hierarchies with no md files was performance. We didn't want to give you a loading experience on the tree until the job completes doing the check for md files in all hierarchies. The documentation was a mistake from our side, my apologies for that. Would having some sort of a "clean my tree" option work for you where onclick, we clean up the tree? I would love to understand how you have structured your code and documentation.

[DanJ210]

@adramasu A "clean my tree" button would be fine if it removed folders that didn't have .md files. The warning about naming convention is confusing to me because I'm not seeing a problem with naming except a folder with a space in it and then the .vscode folder. Should the Wiki from code generator always leave out the .vscode folder by default? If not, every .Net Code application that I build with VS Code will always at least generate a .vscode folder with a warning in the Wiki when that folder is most likely never wanted in the Wiki.

[JoeSchmeltzer]

Thanks for your response @adramasu. I understand your concern with performance. Yes, some button to clean up the folders after the job is complete would work, or even better: have it automatically clean up the folders once the job is complete.

As for the structure of our code and documentation: we are in the unenviable but very common position of trying to add documentation long after the code has been written. We have a vast folder structure with many applications for all areas of the company, so when I wanted to start writing internal documentation for developers, I figured it would make the most sense to put the .md files right in with the code and so this Publish Code as Wiki looked perfect.

If you add a clean-up button or some similar feature, please let me know. Thank you.

[adramasu]

@DanJ210 I understand your concern on .vscode. Would the clean my tree action solve this problem? In the meantime, we will look at how we can hide all "." from the tree. Thank you.

[DanJ210]

@adramasu It would depend what the clean my tree action would do but if it removed the warning folders or any folder with no .md file then yes I would be very happy with that.

[adramasu]

@DanJ210 and @JoeSchmeltzer, there is a suggestion ticket for the same. Please upvote this suggestion ticket.

[thomps23]

@chcomley per the comment below, is there a doc issue here beyond the feature suggestion?

@adramasu, I was under the same impression as @DanJ210 that folders without .md files wouldn't show up in the wiki. I thought that was the case because of this documentation: https://docs.microsoft.com/en-us/azure/devops/project/wiki/publish-repo-to-wiki?view=azure-devops#publish-a-git-repository-to-a-wiki-1

Here's the line from the article:
"Choose Publish. The wiki repo is populated with the Markdown files and folders included within the repo you selected. If a sub-folder does not contain a Markdown file, it doesn't appear in the Wiki."

Trying to start a wiki from my code that shows every single folder is pretty unusable. It is impossible to find where the actual documentation is. If that's the case, I might as well just keep my wiki separate from my code. I was hoping that the "publish wiki from code" option would detect where I have .md files and display them in a hierarchy that matches our code repository. Then as we add .md files, they would start to show up in the wiki. Is that not correct? Is there something I'm missing here? Thanks.

[JoeSchmeltzer]

@thomps23, the document issue I see is that the document I linked to in my comment says this: "If a sub-folder does not contain a Markdown file, it doesn't appear in the Wiki". However, that is not true. As of the last time I tried, which was in March when this thread started, it created ALL folders, regardless of whether they contained an .md file or not.

[chcomley]

Hi @danj210 and @JoeSchmeltzer,

We removed this, "If a sub-folder does not contain a Markdown file, it doesn't appear in the Wiki" and added this, "The wiki TOC contains the following: A parent page for each sub-folder defined within the published folder, even if it doesn't contain any Markdown files."

Do you feel that adequately clarifies things? Please let me know and thank you for all of your feedback.

[JoeSchmeltzer]

@chcomley, that does clarify things. Of course, I wish the previous statement were true! That's what I'd really like to see! But thank you for the clarification.

[DanJ210]

@chcomley yes it does clarify things. Are we able to report feedback on the discomfort caused with all of the folders created that do not have markdowns and have warning signs on them and how that can be very poor for stakeholders to see? Or do we need to report the feedback in another place?

I've even added markdown files to the warning folders and the warning sign doesn't go away nor does the markdown file get picked up. There has to be a better way to solve what most will probably see as not very nice to look at and navigate.

Please don't mistake my above statements as not appreciating the work because I do very much. I'm just being completely honest. It looks really bad when ALL folders are picked up when some shouldn't be and they all have warning labels. It confuses those stakeholders who aren't very tech savvy and makes me look silly when I'm pushing these services.

[chcomley]

Hi @DanJ210, we always appreciate honesty! Please report your feedback here. Thank you!

[DanJ210]

@chcomley The link takes me to where I originally started. Reporting a bug or requesting a feature on the community site. I'm not seeing anywhere that someone can report feedback.

[chcomley]

You can provide your feedback within a "feature request." Consider it a suggestion ticket.
I would upvote this one, and then create a new "feature request" with your individual feedback if you'd like. Thanks very much!