Re: New website design: help needed

--===============6921942974080205331==
Content-Type: multipart/alternative;
	boundary="Apple-Mail=_C6AE7D90-0B67-42B4-816C-09700E25DEFA"


--Apple-Mail=_C6AE7D90-0B67-42B4-816C-09700E25DEFA
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=us-ascii

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 <mleonov-g/[email protected]> wrote:
>=20
> Hello
>=20
> 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.
>=20
> 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=3Dcop=
y#code-copy-button
> For example, the mentioned theme also offers admonitions:
> https://squidfunk.github.io/mkdocs-material/reference/admonitions/
>=20
> 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
>=20
> 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.
>=20
> Cheers
> Max
>=20
>=20
> On Monday, February 17th, 2025 at 7:31 AM, Yury V. Zaytsev via =
mc-devel <mc-devel-+hD5IHI5XseWCegYutOAJTiNl0CLU6MPYPYVAmT7z5s@public.gmane.org> wrote:
>=20
>> Hi everyone,
>>=20
>> 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.
>>=20
>> 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 .
>>=20
>> In terms of requirements, I can think of the following:
>>=20
>> * Ideally clean and light design (think terminalcss.xyz), accessible =
and browsable with both text mode / legacy browsers and modern software.
>>=20
>> * 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/ .
>>=20
>> * The implementation should be HTML5, using some static generator - =
maybe hugo or mkdocs?
>>=20
>> * There should be room for an AdSense plug.
>>=20
>> 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.
>>=20
>> Thanks in advance if anyone gets back to me...
>>=20
>> All the best,
>> Yury
>> --
>> mc-devel mailing list
>> mc-devel-+hD5IHI5XseWCegYutOAJTiNl0CLU6MPYPYVAmT7z5s@public.gmane.org
>> https://lists.midnight-commander.org/mailman/listinfo/mc-devel


--Apple-Mail=_C6AE7D90-0B67-42B4-816C-09700E25DEFA
Content-Transfer-Encoding: quoted-printable
Content-Type: text/html;
	charset=us-ascii

<html><head><meta http-equiv=3D"content-type" content=3D"text/html; =
charset=3Dus-ascii"></head><body style=3D"overflow-wrap: break-word; =
-webkit-nbsp-mode: space; line-break: =
after-white-space;"><div>Hey,</div><div><br></div><div>Thanks for these =
helpful insights!</div><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>Both MkDocs and Hugo will be a learning =
experience, but probably MkDocs would be more valuable to master, even =
though Hugo is more generic.</div><div><br></div><div>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.</div><div><br></div><div>I guess one of the =
most important questions is whether we will have a wiki in the future or =
not...</div><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div><div>The current use for Wiki is as =
follows:</div><div><br></div><div>1. Landing page</div><div>2. Changelog =
entry collection</div><div>3. Developer documentation</div><div>&nbsp; - =
Coding style</div><div>&nbsp; - Release process</div><div>&nbsp; - =
...</div><div>4. User documentation</div><div><br></div><div>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?</div></div><div><br></div><div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>Is there anyone willing to develop a =
nice custom (blue, light/dark) color scheme and basic MkDocs setup for =
m-c.o?</div><div><br></div><div>P.S. Apparently MY QNAP project made a =
nice hi-res logo:</div></div><div><br></div><div><a =
href=3D"https://www.myqnap.org/product/midnight-commander-cli/">https://ww=
w.myqnap.org/product/midnight-commander-cli/</a></div><div><br></div><div>=
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.</div><div><br></div><div>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.</div><div><br></div><div>All the =
best,</div><div>Yury</div><div><br =
id=3D"lineBreakAtBeginningOfMessage"><div><br><blockquote =
type=3D"cite"><div>On 19. Feb 2025, at 01:06, Max =
&lt;mleonov-g/[email protected]&gt; wrote:</div><br =
class=3D"Apple-interchange-newline"><div><div>Hello<br><br>Indeed, =
MkDocs or Hugo are the best two options.<br>Both are terminal browser =
friendly, but you'd better test your theme of choice.<br>In both, you =
can write page content in Markdown, which means that any developer can =
contribute or update content.<br>And both can be hosted on GitHub with a =
custom domain and maybe some pipelines.<br><br>If you go the =
https://www.mkdocs.org/ route, then I recommend the following =
theme:<br>https://squidfunk.github.io/mkdocs-material/ (best MkDocs =
theme IMO)<br>Configuring and building the website is simple, which =
translates into maintenance time savings.<br>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:<br>https://squidfunk.github.io/mkdocs-material/reference/code-bloc=
ks/?h=3Dcopy#code-copy-button<br>For example, the mentioned theme also =
offers =
admonitions:<br>https://squidfunk.github.io/mkdocs-material/reference/admo=
nitions/<br><br>With Hugo, you can provide content in some other formats =
including HTML, which might be of hypothetical use for reusing some =
existing HTML =
pages:<br>https://gohugo.io/content-management/formats/<br>Hugo also =
offers a number of docs themes: =
https://themes.gohugo.io/tags/docs/<br>Just avoid a theme that is not =
actively maintained.<br>If you're looking for a clean Hugo them with =
support for docs and the code copy button,<br>then you can try this one: =
https://github.com/imfing/hextra<br>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<br><b=
r>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.<br>In the end, I bet you'll get more or =
less the same results whether you settle on MkDocs or =
Hugo.<br><br>Cheers<br>Max<br><br><br>On Monday, February 17th, 2025 at =
7:31 AM, Yury V. Zaytsev via mc-devel =
&lt;mc-devel-+hD5IHI5XseWCegYutOAJTiNl0CLU6MPYPYVAmT7z5s@public.gmane.org&gt; wrote:<br><br><blockquote =
type=3D"cite">Hi everyone,<br><br>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.<br><br>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 .<br><br>In terms of =
requirements, I can think of the following:<br><br>* Ideally clean and =
light design (think terminalcss.xyz), accessible and browsable with both =
text mode / legacy browsers and modern software.<br><br>* 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/ .<br><br>* The implementation =
should be HTML5, using some static generator - maybe hugo or =
mkdocs?<br><br>* There should be room for an AdSense plug.<br><br>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.<br><br>Thanks in advance if anyone =
gets back to me...<br><br>All the best,<br>Yury<br>--<br>mc-devel =
mailing =
list<br>mc-devel-+hD5IHI5XseWCegYutOAJTiNl0CLU6MPYPYVAmT7z5s@public.gmane.org<br>https://lists.midnight-co=
mmander.org/mailman/listinfo/mc-devel<br></blockquote></div></div></blockq=
uote></div><br></div></body></html>=

--Apple-Mail=_C6AE7D90-0B67-42B4-816C-09700E25DEFA--

--===============6921942974080205331==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

-- 
mc-devel mailing list
mc-devel-+hD5IHI5XseWCegYutOAJTiNl0CLU6MPYPYVAmT7z5s@public.gmane.org
https://lists.midnight-commander.org/mailman/listinfo/mc-devel

--===============6921942974080205331==--