Allow to optionally decouple file and directory names from display names about madness

[DannyBen]

This was an intentional design choice.

There are plenty of markdown servers and markdown static site generators that provide you with this functionality. The price, is (usually) too much configuration and conventions.

Madness is designed so you can just "plop" some markdowns in some folders, without many structure limitations, and be able to instantly view them in a browser.

I for one, was constantly annoyed by the fact that each of my documents had two names: "one-filename.md" and "One Filename" as a title. Changing your mind, always means you have to rename twice.

Note that the title of the document (its H1) can be anything you want. If not provided in the document, it will take the name of the file.

I am working both on Windows and on Linux, so I am aware of both the case insensitivity annoyance, and the filenames with spaces annoyance. This is a compromise I was willing to accept to avoid having to maintain two names for each document.

This behavior is unlikely to change. Some of the reasons:

1. I would like to keep madness simple and efficient.
2. Directories that do not start with a capital letter are ignored by design - to allow places for css, assets and other "hidden" directories.
3. The sidebar navigation is generated on every page you load. It needs to be fast. Right now, it is a simple ls of the viewed directory. Having to read the documents, or any "meta" configuration in order to generate it, will have a performance penalty, especially on larger documentation bases.

[quijote]

Thank you for giving some background on why things are how they are.

After some further thinking and consultation with colleagues, I would still prefer to not introduce a Git repository used by multiple devs that relies heavily on the use of spaces and capital letters in file and directory names.

I understand it is a tradeoff and keeping maintaining 3 things (file name, short display name for navigation and h1) is sometimes annoying. But having a short title (side bar, breadcrumbs) and long title (h1) clearly provides benefits. This proposal aims at only having file name and h1 for >90% of all files. But for the few exceptions I would like to give authors a choice: Either call file HTTP requests.md (introduce paths with spaces and capitalization in your Git repo) or call file http_requests.md and add one additional line <!--title:HTTP requests-->. In my case I would always choose the latter and accept the maintenance overhead that comes with it.

I will look a bit more at alternative CSS servers since I did not find something as nice as Madness yet. I like that it can serve any folder with 0 configuration but still allows to adapt the output a bit with .madness.yml (e.g. one line custom CSS to make the fonts smaller). Aesthetically it also looks great out of the box, which is great for someone like myself who does not do much design or frontend development. Full text search is also nice and often lacking from static content generators.

I think it might be possible to overcome all 3 reasons against the proposal.

In my deployment I already replaced exclude: ['^[a-z_\-0-9]+$'] with exclude: ['css', '^_.+$'] so that lower case folders and files are also shown while my assets are hidden in folders like _images (similar to another static content generator I used). I understand that changing defaults is very difficult and maybe not desirable anymore at the moment.

I think "Change display name by convention" could be implemented without having noticeable negative effects on efficiency.

Even in a very large documentation base, I would assume that most folders have less than 10 subfolders or markdown files. So I think "Change display name by explicit override" could also be implemented quite fast by caching display names in memory (map key being file path + last modification time of the file). In some production environment (Kubernetes) served files would never change and map key could even just be the file path without checking the last modification time on every request.

If the proposal is simply not a good fit for Madness at this stage, I could image running a slightly modified (forked) version in my own deployment. I could share my experience with that again after a while.

[DannyBen]

I think "Change display name by convention" could be implemented without having noticeable negative effects on efficiency.

I don't see how this will work.
If there is a convention that that removes underscores and capitalizes the first letter, filenames like http_request.md or public_api.md will not be properly converted ("Http request" and "Public api").

[quijote]

Acronyms like HTTP and API were meant to demonstrate why both parts of the proposal are necessary to cover all cases. Most titles can simply be derived correctly from the file name. Few titles must be explicitly set if the default casing rules do not produce the desired result.

After doing some research, I think that using Title Case will work better than Sentence case. That is because many titles could contain special nouns that require capitalization.

There seems to be a nice Ruby Gem that takes care of capitalization:
https://github.com/granth/titleize

So I would try to optionally add gsub('_', ' ').titleize to String#to_label.

I tried the following:

require "titleize"

module StringRefinements
  refine String do
    def remove(regex)
      gsub regex, ''
    end
    def to_label
        remove(/^\d+\.\s*/).remove(/\.md$/).gsub('_', ' ').titleize
    end
  end
end

using StringRefinements

files = [
  "bounty_hunters",
  "ewoks",
  "galactic_empire",
  "jedi_order",
  "1._the_jedi_code",
  "2._educational_hierarchy",
  "3._technology_and_abilities",
  "4._the_four_councils",
  "5._the_sith_organization",
  "6._non-jedi_force-wielders",
  "naboo",
  "old_galactic_republic",
  "rebel_alliance",
  "separatists_and_trade_federation",
  "sith_lords",
  "stormtroopers",
  "the_first_order",
  "the_resistance"
]
files.each { |x| puts x.to_label }

Which outputs:

Bounty Hunters
Ewoks
Galactic Empire
Jedi Order
The Jedi Code
Educational Hierarchy
Technology and Abilities
The Four Councils
The Sith Organization
Non-Jedi Force-Wielders
Naboo
Old Galactic Republic
Rebel Alliance
Separatists and Trade Federation
Sith Lords
Stormtroopers
The First Order
The Resistance

[DannyBen]

Exactly. Automatic transformation of a filename to a label is only part of the solution, which adds the need for yet another part to the solution, which adds complexity to the code base and to the user's understanding of how to use it.

Instead of trying to solve a problem by introducing more problems, madness chose to not have the problem in the first place; A document's file name, is its.... name. Simple.

As I mentioned, this is a core design concept in madness and unlikely to change.

If this feature is important to you, I can recommend Retype - it is not a markdown server, but rather a static site generator, but it is great, I am using it myself, and it supports your requirement out of the box.

[quijote]

Thank you for your suggestion to use Retype. It looks nice but I decided against it due to the rather restrictive license.

Feel free to close this ticket. I took some inspiration from the way Markdown is presented by Madness and started implementing my own minimalistic Markdown server in Quarkus Supersonic Subatomic Java last night that I will deploy as a GraalVM Native Image in Kubernetes instead of the Madness docker container. I only implemented the first part of this proposal (change display name by convention) so far, but I am already happy with the result for all documents I am hosting at the moment.

Madness is still a great project and helped me a lot to get started with my document hosting initiative. All the best to you and your open source project.

[DannyBen]

Alright then, good luck.