I’m pondering a new tool that would be designed to generate a documentation site from markdown files in a project source repo. This has been discussed here before. Most of my site generation needs are not generating new sites (blogs, etc), but rather extracting documentation for various projects I work on. I believe documentation should live with the source code. This has several benefits:
is easier to maintain documentation if it can be updated when the developer is working on the source code (monorepo)
you can view the documentation in github
every version of the project has relevant documentation included with it
It would be a simpler translation of markdown to html. With Zola, you get nice URLs like:
This way, images and assets could continue to live in the same directories and would be a more one-to-one mapping of the folder structure and markdown you might find in a project docs/ folder.
What are the drawbacks with generating mypage.html files instead of mypage/index.html?
Again, I’m not proposing Zola change to do this, but rather start a new project focused on project documentation. Asking here as I really like Zola, and you might have insight into tradeoffs with this approach.
links could be rewritten by web-server, not big deal, but might I ask one thing ontop - I read your link with previous discussion and cannot fully understand what the diff between new tool and zola?
And easily generate a documentation site. I’ve not found an easy way to do this yet with any of the existing static site (hugo, zola, docusaurs, etc) generators. Most generators want the images to all live in a special “public” dir, and not alongside the markdown content – Zola is a big improvment in this regard, but there is still the problem of needing to follow the development/index.md pattern instead of development.md if development includes images that are in the same directory.
I can create processes (https://github.com/simpleiot/docs.simpleiot.org/blob/main/envsetup.sh) to preprocess the above and move everything into a structure Zola likes, create re-write rules in the web server as you mentioned, etc, but these are fussy, complex, and since I’m doing this over and over, I would like a tool that can do a simple conversion of a directory of static markdown files and images into a site … maybe I should look at pandoc more …
For this special case, a minimal configuration tool would be nice that developers could just run directly on their source repos.
My earlier posts in this thread have been flagged – I’m sorry for posting here and will stop discussing this issue as this is obviously outside the interest and scope of this community.