Feature: Plain Markdown generator. by BroDudeGuyMan · Pull Request #88 · lawmurray/doxide

BroDudeGuyMan · 2026-03-03T17:27:16Z

Problem

Doxide currently only outputs Markdown that is not compatible with GitHub webview, and other Markdown viewers. This is okay for larger projects, but small personal repositories often rely on GitHub webview for source documentation.

Fix

New Generator

I have added a new class called PlainMarkdownGenerator that replaces all Mkdoc-specific Markdown with standard, fully supported syntax. Icons have also been replaced with near-identical Unicode characters.
Use the new generator with: doxide gitdoc

Init options

There is a new option for the init sub-command:

doxide init --plain

This will create doxide.yaml as normal, as well as the output directory, but will skip creating mkdocs.yaml and the web content directories. This leaves only Markdown, with no other dependencies.

How this helps

Now Doxide can be used as both a documentation hosting tool, and a local documentation manager. All without the hassle of manually editing files and removing directories.

Changes:

Added src/PlainMarkdownGenerator.hpp
Added src/PlainMakrdownGenerator.cpp
Added bool Driver::plain
Edited Driver::init() to Driver::init(bool plain_md)
Edited CMakeLists.txt to add set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
Added cmbuild.sh to simplify the build process with a dedicated output directory.
Added documentation to docs/getting-started.md and docs/running.md

…kdownGenerator.hpp and .cpp. Added new subcommand 'gitdoc' to use the PlainMarkdownGenerator. Added Driver::git_build() to utilize PlainMarkdownGenerator functions instead of MarkdownGenerator.

…rks with `gitdoc` command to have the output directory contain only plain Markdown

Corrected the spelling of 'unsupported' in the documentation.

BroDudeGuyMan

The cmbuild.sh script is not a dependency and can be removed from the repo. It's simply a helpful script to clean the build dir, configure CMake, and build the project.

lawmurray

Thanks for working on this @BroDudeGuyMan. I've reviewed the code.

The major issue is that you have copied all of MarkdownGenerator.cpp to PlainMarkdownGenerator.cpp before making your changes in there, which means there is now a lot of duplicated code. That creates a maintenance headache for future: any fixes to that code will need to happen in both files in future. So we can't do that.

Can you instead integrate your changes into MarkdownGenerator.cpp? Similar to what you have done in Driver.cpp, were you just use a few if (plain_md) conditionals to act differently. There are only 10-20 lines that you have had to change in the Markdown generator, so this is the best way.

If you can do that, I can review again.

lawmurray · 2026-03-11T11:17:10Z

The cmbuild.sh script is not a dependency and can be removed from the repo. It's simply a helpful script to clean the build dir, configure CMake, and build the project.

Let's remove this file too. Everyone has their own workflows, and they can make such a script themselves if that's how they prefer to work.

BroDudeGuyMan · 2026-03-11T13:17:36Z

You got it @lawmurray. I can get that done today.

BroDudeGuyMan · 2026-03-11T14:29:58Z

@lawmurray I've made the changes. Now, when using init, a style: field is added to the doxide.yaml file. This is referenced in the generator to make the proper adjustments.

Typo fix

lawmurray · 2026-04-16T13:37:49Z

+### For small projects
+If you don't want the Mkdocs noise, you can run:
+```
+doxide gitdoc


I don't see any gitdoc command implemented. Besides, a separate command is not the preferred approach, so this can be removed.

lawmurray · 2026-04-16T13:38:11Z


 Add at least `doxide.yaml` to version control, and the other files if you intend to use Material for MkDocs (highly recommended for a quick start---you can always try something else later).
+
+### For small projects


No need to document this here, as it's mean to be a "quick start" section.

lawmurray · 2026-04-16T13:39:36Z

-      callback([&]() { driver.init(); });
+  auto init_cmd = app.add_subcommand("init",
+      "Initialize configuration files.");
+  init_cmd->add_flag("--plain",


I'll elaborate on the discussion page, but I think we should just add a --style command-line option that takes values plain and mkdocs-material. Then doxide init --style plain can do what you want, and doxide build --style plain or putting style: plain in doxide.yaml can do what you want.

That makes sense.

lawmurray · 2026-04-16T13:39:47Z

 #include "YAMLParser.hpp"
 #include "CppParser.hpp"
 #include "MarkdownGenerator.hpp"
+#include "PlainMarkdownGenerator.hpp"


lawmurray · 2026-04-16T13:40:17Z

 */
 static const char* init_doxide_yaml =
-R""""(title:
+R""""(style:


Use the order title, description, style, files. This is a user-editable file, and having style first may confuse.

lawmurray · 2026-04-16T13:41:18Z

 }

-void Driver::init() {
+void Driver::init(bool plain_md) {


I don't see the need to have the bool plain_md parameter. Why not just check the style member variable?

lawmurray · 2026-04-16T13:41:33Z

+        "style: plain");
+  } else {
+    doxide_yaml = std::regex_replace(doxide_yaml, std::regex("style:"),
+        "style: mkdocs");


Let's use mkdocs-material, it's more precise.

lawmurray · 2026-04-16T13:42:00Z

   * Create a new configuration file.
   */
-  void init();
+  void init(bool plain);


Again, not seeing the need for this parameter, I think there are better ways.

lawmurray · 2026-04-16T13:42:37Z

+  /**
+   * Build GetHub webview ready documentation.
+   */
+  void git_build();


This shouldn't be a command, let's just use a --style plain command-line option.

lawmurray · 2026-04-16T13:54:57Z

+  /**
+   * Whether to remove Mkdocs noise.
+   */
+  bool plain;


This seems redundant with having the style member set to plain? If so, let's remove it, and just use the style member.

lawmurray · 2026-04-16T13:58:27Z

+  /**
+   * Entity style. This is used to generate certain types of Markdown.
+   */
+  std::string style;


This means that every entity has its own style attribute, which will slow things down considerably and is unnecessary. Only Driver and MarkdownGenerator should need to know the style.

lawmurray · 2026-04-16T13:59:01Z

  std::string filename;  // file name for this entity
  std::string childdir;  // directory name for children, relative to filename
  if (entity.type == EntityType::ROOT) {
+    style = entity.style;


As above, add style to Driver and MarkdownGenerator, but not each Entity.

lawmurray · 2026-04-16T14:00:05Z

-      out << "(" << childdir << sanitize(child->name) << "/index.md)" << std::endl;
-      out << ":   " << line(brief(*child)) << std::endl;
-      out << std::endl;
+      if (style == "plain") {


Don't do a string comparison each time, as these are tight inner loops, and doing so will harm performance considerably. Instead, do the comparison once, and store the result in a bool.

lawmurray · 2026-04-16T14:00:49Z

        out << std::endl;
-        out << "!!! macro \"" << htmlize(line(child->decl)) << '"' << std::endl;
+        if (style == "plain") {
+          out << "> ＃**Macro**" << std::endl << "> " << htmlize(line(child->decl)) << std::endl;


This unicode character is broken for me. Perhaps it's not in all fonts. Is there an alternative?

lawmurray · 2026-04-16T14:01:09Z

I think this shouldn't exist any longer.

lawmurray · 2026-04-16T14:01:20Z

 /docs/demo
 /.cache
 /src/config.h
+cmbuild.sh


No longer exists.

lawmurray · 2026-04-16T14:01:37Z

 cmake_policy(SET CMP0074 NEW) # use <PackageName>_ROOT to look for packages

 set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)


Can you explain what this does?

lawmurray · 2026-04-16T14:01:43Z

  src/JSONCounter.cpp
  src/JSONGenerator.cpp
  src/MarkdownGenerator.cpp
+  src/PlainMarkdownGenerator.cpp


lawmurray · 2026-04-16T14:14:00Z

Thanks for the update here @BroDudeGuyMan. I've reviewed and left some comments throughout.

What I'd suggest is that we just add a --style command-line option. It can work the same way as --title and --description already do, so:

doxide init --style plain would set style: plain in doxide.yaml, and not generate the extra JavaScript and CSS files that are meant for Material for MkDocs.
style: plain in doxide.yaml, possibly overridden with doxide build --style plain on the command line, would generate the simpler Markdown that you've prepared.

BroDudeGuyMan and others added 4 commits March 3, 2026 00:44

Added CMAKE_EXPORT_COMPILE_COMMANDS to CMakeLists.txt. Added PlainMar…

55d62ee

…kdownGenerator.hpp and .cpp. Added new subcommand 'gitdoc' to use the PlainMarkdownGenerator. Added Driver::git_build() to utilize PlainMarkdownGenerator functions instead of MarkdownGenerator.

Added flag --plain to init sub-command to remove Mkdocs noise. Wo…

eedc789

…rks with `gitdoc` command to have the output directory contain only plain Markdown

Added documentation for the new commands.

b58c3db

Fix typo in running.md

f5ab1cb

Corrected the spelling of 'unsupported' in the documentation.

BroDudeGuyMan commented Mar 4, 2026

View reviewed changes

lawmurray requested changes Mar 11, 2026

View reviewed changes

BroDudeGuyMan added 2 commits March 11, 2026 10:23

Added conditionals, get style from doxide.yaml, removed gitdoc command

2780904

removed cmbuild.sh from repo

733b00a

Update MarkdownGenerator.cpp

77a7b46

Typo fix

lawmurray reviewed Apr 16, 2026

View reviewed changes

Comment thread src/PlainMarkdownGenerator.hpp

Copy link
Copy Markdown

Owner

lawmurray Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this shouldn't exist any longer.

lawmurray reviewed Apr 16, 2026

View reviewed changes

Comment thread .gitignore

/docs/demo

/.cache

/src/config.h

cmbuild.sh

Copy link
Copy Markdown

Owner

lawmurray Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No longer exists.

lawmurray reviewed Apr 16, 2026

View reviewed changes


		Add at least `doxide.yaml` to version control, and the other files if you intend to use Material for MkDocs (highly recommended for a quick start---you can always try something else later).

		### For small projects

Uh oh!

Conversation

BroDudeGuyMan commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Fix

New Generator

Init options

How this helps

Changes:

Uh oh!

BroDudeGuyMan left a comment

Choose a reason for hiding this comment

Uh oh!

lawmurray left a comment

Choose a reason for hiding this comment

Uh oh!

lawmurray commented Mar 11, 2026

Uh oh!

BroDudeGuyMan commented Mar 11, 2026

Uh oh!

BroDudeGuyMan commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lawmurray commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

BroDudeGuyMan commented Mar 3, 2026 •

edited

Loading

BroDudeGuyMan commented Mar 11, 2026 •

edited

Loading