Hey, Thanks for these helpful insights!
If I had to do it myself, I'm still a bit torn between using some sort of Bootstrap and doing a few simple HTML pages, or bolting those pages on top of Hugo, or taking the plunge into MkDocs. I guess Jekyll is no longer as interesting an option as it was a decade ago. Other systems like Sphinx, which has been around forever, or GitBook are way too documentation oriented and have a high barrier to entry. Also, we don't have nearly enough content to justify the complexity of such tools. Both MkDocs and Hugo will be a learning experience, but probably MkDocs would be more valuable to master, even though Hugo is more generic. The Material Pointer looks interesting, maybe it's the best way to go. Ideally I'd have to make a color scheme and disable everything that can be disabled :) and see what happens. I guess one of the most important questions is whether we will have a wiki in the future or not... If not, then suddenly a MkDocs website becomes much more interesting and there is actually some content (like coding guidelines, release workflow, etc.) that would fit into the scheme. If we still have a wiki, just on GitHub, then there won't be much content other than the landing page, and that kind of puts me on the fence about MkDocs. That was my original thought, but maybe it's not a good one. The current use for Wiki is as follows: 1. Landing page 2. Changelog entry collection 3. Developer documentation - Coding style - Release process - ... 4. User documentation Maybe if we can collect release notes using GitHub releases in draft mode, this kind of takes care of the most important use for the wiki. I wonder if release drafts are visible only to the users who created them, or to all repository committers? The rest will then fit nicely into the concept of MkDocs website... Small things can be changed directly by committing edited Markdown files, even using the web editor - which makes it not much different from a wiki. Bigger changes can be done via PR. It would be nice to have preview deploys, but that has to be implemented manually. GitHub is apparently working on it since 2021, but no ETAs yet... So it's not a requirement and can be done manually if needed. Is there anyone willing to develop a nice custom (blue, light/dark) color scheme and basic MkDocs setup for m-c.o? P.S. Apparently MY QNAP project made a nice hi-res logo: https://www.myqnap.org/product/midnight-commander-cli/ P.P.S. We can also move some documentation content out of the main repository later, where it doesn't have much exposure anyway... like super old FAQs, HACKING, etc. One thing I'm not very positive about is having MkDocs in the main repository. But maybe it's a wrong outdated idea. I think we can start separately and merge it later. All the best, Yury > On 19. Feb 2025, at 01:06, Max <[email protected]> wrote: > > Hello > > Indeed, MkDocs or Hugo are the best two options. > Both are terminal browser friendly, but you'd better test your theme of > choice. > In both, you can write page content in Markdown, which means that any > developer can contribute or update content. > And both can be hosted on GitHub with a custom domain and maybe some > pipelines. > > If you go the https://www.mkdocs.org/ route, then I recommend the following > theme: > https://squidfunk.github.io/mkdocs-material/ (best MkDocs theme IMO) > Configuring and building the website is simple, which translates into > maintenance time savings. > If you choose MkDocs, you'll have to manually enable the code copy button in > this theme as it has more features than the bare MkDocs: > https://squidfunk.github.io/mkdocs-material/reference/code-blocks/?h=copy#code-copy-button > For example, the mentioned theme also offers admonitions: > https://squidfunk.github.io/mkdocs-material/reference/admonitions/ > > With Hugo, you can provide content in some other formats including HTML, > which might be of hypothetical use for reusing some existing HTML pages: > https://gohugo.io/content-management/formats/ > Hugo also offers a number of docs themes: https://themes.gohugo.io/tags/docs/ > Just avoid a theme that is not actively maintained. > If you're looking for a clean Hugo them with support for docs and the code > copy button, > then you can try this one: https://github.com/imfing/hextra > just might want to set a wider page width because the default text column is > quite narrow: > https://imfing.github.io/hextra/docs/guide/configuration/#page-width > > The bottom line is the learning curve: MkDocs is easier to use, whereas Hugo > is more complex due to a lot more features and as a result will probably take > more time. > In the end, I bet you'll get more or less the same results whether you settle > on MkDocs or Hugo. > > Cheers > Max > > > On Monday, February 17th, 2025 at 7:31 AM, Yury V. Zaytsev via mc-devel > <[email protected]> wrote: > >> Hi everyone, >> >> As I'm slowly working on hammering many of the necessary nails into the >> coffin of our old Trac, I thought I'd ask for some help in designing a new >> website. >> >> My general idea is this: most of the Trac content will be migrated to hosted >> services in the future, including the wiki. However, it would be nice to >> still have a landing page / index on midnight-commander.org . >> >> In terms of requirements, I can think of the following: >> >> * Ideally clean and light design (think terminalcss.xyz), accessible and >> browsable with both text mode / legacy browsers and modern software. >> >> * The content should be similar to the current main page. I think it would >> be best to split it into several pages, but I wouldn't be completely against >> the idea of scrollable sections. As an example of some recent sites that >> caught my eye as being nice in terms of layout, structure and content, I can >> mention the new PCRE2 homepage: https://pcre2project.github.io/pcre2/ . >> >> * The implementation should be HTML5, using some static generator - maybe >> hugo or mkdocs? >> >> * There should be room for an AdSense plug. >> >> Let me know if you can contribute. Ideally, if you have any questions, we >> can discuss that on the list, and then eventually you post your work as a >> GitHub repository / GitHub pages and we can fork it into our organization >> when it's time to move. >> >> Thanks in advance if anyone gets back to me... >> >> All the best, >> Yury >> -- >> mc-devel mailing list >> [email protected] >> https://lists.midnight-commander.org/mailman/listinfo/mc-devel
-- mc mailing list [email protected] https://lists.midnight-commander.org/mailman/listinfo/mc
