Open rollniak opened 2 years ago
I'm curious about second bullet. Do you have some other tool in mind? And yes, mkdocs doesn't have multilingual support.
To be honest it's difficult to say right now. It's important to choose the tools for our needs but it's also important to know the people who are going to work with it. e.g: having a tool written in a language nobody know imply a learning curve impossible to pass depending on the time we have.
I also need to know if your requirements as changed since the issue written by @olevole. :)
I already got a problem when I tried to add an admonition on between line 117 and 131 on the bhyve with dhcpd tutorial with code block nested in it. I'm not an huge fan of Markdown in the case of a documentation project like CBSD
Another Markup Language we can think of is reStructuredRext which is used with sphinx. I don't used them for years and I should try out to see how the CBSD documentation could be rendered.
I personally prefer ASCIIDoc as a Markup language for a documentation like this. I don't get the problem I mentioned earlier with it on Jekyll. The FreeBSD community show us a good use case of ASCIIDoc + Hugo with the FreeBSD handbook. We also have Antora but it doesn't have multilingual support out of the box and I never tried it. I know that Jekyll has a non native support of ASCIIDoc support and some plugins for internalization.
Based on the @olevole mentioned earlier, the multilingual part can be see as a tree like this:
I presume the 12.X is going to be deprecated in a year and an half. So we can focus only on the 13.X and point out to the old documentation in meantime. On the old website we can point to cbsd.io for 13.X and newer version of cbsd. If we finish the migration earlier then maybe we could also migrate the 12.X on cbsd.io.
Here another resource about writing modular documentation
@rollniak > Stop updating the cbsd-wwwdoc repo for the documentation.
The two main reasons why the old repository is still being updated are:
1) the new site is still missing a lot of content from the old site - this causes update problems on two sites at the same time. 2) we cannot transfer 70% of the content because the new engine does not support multilingualism. I still want to support it.
@olevole ping
The new site seems to be missing a few big articles and some updates (besides the complete absence of the ru part). Unfortunately, next month I will be very busy, sorry!
Could you point at what's missing in English docs? Do we need anything besides ru? I've seen de, for example.
Hello,
I have some suggestions to help with the documentation migration from bsdstore.ru to cbsd.io and in general.
Here some suggestions. :)
It is lot of ideas and I'm open to your feedback. I may need some guidance since I'm new in the project. :)