Seeking advice for Multi-platform documentation

Off-Topic
#1

I am looking for advice on how to develop and maintain documentation for multiple platforms.

I have created an app in Xojo that I have built for MacOS, Win, and Linux. The app has a Help File that varies depending on the target platform. The variations are mostly platform-specific images, but a bit of the help file text varies also. To create these Help Files, I used Notion to create the file for one platform, then duplicated the note and modified it to create the file for the next platform, and again for the last platform. In the end, I have three distinct help files, each with very similar core text, but different images. Maintaining three distinct yet very similar files is not ideal.

Thoughts on how to better manage these help files?

Basic requirements: hyperlinked TOC, images, basic styles (headings, etc.). There is probably a simple solution to this, but I have not been successful finding that solution through Web search.

Help Files can be viewed here: Dropbox - InVerse - latest build - Simplify your life

Thanks in advance for any advice!

#2

Hello,

From what you say and depending on your skills, I will use the following

  • Vitepress (or Vuepress)
  • Add an offline search engine if needed (e.g.: vitepress-plugin-search)
  • Create folders macos/linux/windows in the asset folder (/assets/<operating_system>/asset.png)
  • Then the build of the documentation will be generated in 3 different folder ( one for macos, one for windows, one for linus)
  • Add build steps in your xojo project to copy the correct folder
  • Load the documentation into a HTMLViewer

You may need a script to replace paths (to relative path) in the files

#3

@Julien_Courtes, thank you for this recommendation!

I pursued this. Was able to install VitePress on my Mac and get it configured. I ran into a roadblock when trying to apply table-of-contents (“[[toc]]”) to a file one level down in my doc tree. For some reason, toc will render at top level, but not below?

Anyway, in my search to figure out how to resolve that issue, I came across pandoc. I have been able to do what I need using pandoc, which is quite powerful.

Thank you again for the suggestion.

#4

Late to the table, but I just this week invested in HelpNDoc which can make online or local HTML help, CHM, PDF, eBook and Word documents from a single source file.
£115