Live docmd and Suggestions

[replicant026]

Hey, a quick thank you. I had started creating my documentation page using VitePress (which, by the way, is just as simple, but I liked docmd and decided to migrate entirely to it).

I loved docmd, here's the website to see it live: https://defast.com.br/docs/

Regarding some points that I think could be improved or that I missed:

• Better documentation: here I'll use VitePress as an example, their documentation page is complete with everything possible, which helps a lot.

• Better Customization:

  • I missed being able to replace the logo with text, or put logo + text. - Natively already can put img or text, logo + text isnt possible by limitations
  • I missed being able to insert links in the header. - Done on 0.5.2
  • Perhaps instead of internationalizing, just leave the strings with text so you can change them; I had to use JS for that.
  • I missed an option to hide the header title when the title is already visible in the text; I had to use JS for that. - Done on 0.5.1
  • I must have made a mistake somewhere, but I had a slight difficulty customizing the sidebar links with colors, hover, etc. - Improoved on 0.5.2

• Perhaps being able to hide the branding natively - Done on 0.5.0
• LaTeX support

Sorry if the text seemed critical, but I really loved docmd and pointed out what I think could be improved.

[pratikrath126]

Thanks for sharing your live site! It looks really clean. Your feedback on customization is very practical—especially the 'logo + text' and 'links in header' points. Those are definitely common requirements for documentation sites. For the LaTeX support, if docmd doesn't support it natively yet, you might be able to inject KaTeX via a custom script as a workaround for now. The idea of exposed strings for localization (instead of a full i18n system) is also a great suggestion for keeping things simple. Have you considered opening these as individual feature requests or even PRs?

[replicant026]

Not yet, I was first trying to launch the site

But I'll set aside some time this weekend to maybe implement solutions instead of just asking.

Actually, injecting LaTeX is a good solution; I hadn't thought of it because I actually only have about 3 simple formulas in the doc, so I didn't think much about it, haha.

[replicant026]

thanks! works perfectly with KaTeX :)

if help, here the code to put in custom.js

// LaTeX suport via KaTeX
document.addEventListener("DOMContentLoaded", function () {
  const katexCSS = document.createElement("link");
  katexCSS.rel = "stylesheet";
  katexCSS.href =
    "https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css";
  katexCSS.crossOrigin = "anonymous";
  document.head.appendChild(katexCSS);

  const katexScript = document.createElement("script");
  katexScript.src =
    "https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js";
  katexScript.crossOrigin = "anonymous";

  katexScript.onload = function () {
    const autoRender = document.createElement("script");
    autoRender.src =
      "https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js";
    autoRender.crossOrigin = "anonymous";

    autoRender.onload = function () {
      renderMathInElement(document.body, {
        delimiters: [
          { left: "$$", right: "$$", display: true },
          { left: "$", right: "$", display: false },
          { left: "\\(", right: "\\)", display: false },
          { left: "\\[", right: "\\]", display: true },
        ],
        throwOnError: false,
      });
    };
    document.head.appendChild(autoRender);
  };
  document.head.appendChild(katexScript);
});

[mgks]

Duly Noted!

[mgks]

@replicant026

• perhaps being able to hide the branding natively

So we just released 0.5.0 now, one of your requests are implemented with this release, and possibly will cover more requests with further releases. Now you can just turn the docmd footer branding off officially:

footer: {
  style: 'minimal',
  branding: false    // no need for custom JS tweaks anymore
}

Don't forget to spread the word. Do share your feedback on the release.

I will keep updating this space with more releases coming.

[mgks]

I missed an option to hide the header title when the title is already visible in the text; I had to use JS for that.

Added extended support in 0.5.1. You can now hide the header. No menu-bar yet, but we're getting there.

layout: {
  header: {
    enabled: true
  }
}

[mgks]

I missed being able to insert links in the header.

Well we've now released a whole menubar option now with 0.5.2, you can add links, icons, and customize it's position and even put optionsMenu in there. It's still an early release so we hope for a much improved and robust version in near future.

I missed being able to replace the logo with text, or put logo + text.

Oh it's already there since the beginning, if you simply remove the logo, the site title will take its place, but unfortunately logo+text is not a thing and possibly won't be in our case.

I must have made a mistake somewhere, but I had a slight difficulty customizing the sidebar links with colors, hover, etc.

Possibly documentation previously was not detailed enough, I have updated the docs but most effective would be using inspect tools in your browser and reuse whatever element you want to in a custom CSS, it will be given priority over default stylesheets.

[replicant026]

wow! Thanks for the quickly updates and improvements !

Can i request one more thing? In vitepress they have a option to display the "Last Updated on DD/MMMM/YYYY HH:mm" using git, its very nice and cool to see. is there a way to implement this too?

Oh i see that documentation has improoved too! thanks!

[mgks]

option to display the "Last Updated on DD/MMMM/YYYY HH:mm" using git

Already in the pipeline, I'm pretty sure we will finish up early and get it somewhere around 0.6.x.

[mgks]

well, not in 0.6.x but in 0.7.8, we now have early adaption for git (inbuilt-plugin) with last commit + commit history + file edit anchor features.
You can check it working live on docs.docmd.io. Will improve a few more tweaks in next release with OpenAPI plugin.

[mgks]

• LaTeX support checked!

Update to 0.6.9 release and install math plugin with:

docmd add math

It's extremely light and seamlessly works with docmd.

Only 1 to go.

[mgks]

And that’s the milestone done. 🎉

i18n is now officially supported from 0.7.0 onwards.

This whole 0.7.x series is going to be a big one and will likely shape the final form of docmd.

Thanks for all the great suggestions, @replicant026.

[replicant026]

@mgks you awessome!

[mgks]

🙏🏼