For example markdown link:

[2.4. Úprava plastové krabičky pro elektroniku](#24-úprava-plastové-krabičky-pro-elektroniku)

leading to a heading within the same webpage:

## 2.4. Úprava plastové krabičky pro elektroniku

correctly generates link:

<li><a href="[#24-%C3%BAprava-plastov%C3%A9-krabi%C4%8Dky-pro-elektroniku](localhost:8667/Test-page#24-%C3%BAprava-plastov%C3%A9-krabi%C4%8Dky-pro-elektroniku)">2.4. Úprava plastové krabičky pro elektroniku</a></li>

but in the heading id diacritics are missing:

<h2><a id='24-prava-plastov-krabiky-pro-elektroniku'></a>2.4. Úprava plastové krabičky pro elektroniku</h2>

therefore the link from above leads to nowhere.

Github generates id looking like this:

<h2><a id="24-úprava-plastové-krabičky-pro-elektroniku"</a>2.4. Úprava plastové krabičky pro elektroniku</h2>

which seems to work fine.

Consider adding something like this:

1. A system folder named _dot
2. In it, any file with a .dot extension (also in subfolders) can be rendered in real time as an image
3. These images can be accessed by the server as _dot/any_folder/whatever.png

Perhaps a convention to ignore folders that start with an underscore.
Will be good for supplying image assets to the docs.

Problem

As of today, Markdown Madness always displays directory and file names 1:1.

This is a good default for simplicity, getting started with a new deployment and to avoid lockin to a specific tool.

However this also has some disadvantages:

• One may want to show characters that are discouraged by filesystems (such as spaces, :, /) or URLs (such as spaces, :, /, ?, #)
• One may want to use capitalization which can cause issues when dealing with case-insensitive filesystems on Windows

In my tests I first optimized directory and file names for final display in Markdown Madness:

Some project title (directory)
  Some document title.md (file)

This will be displayed nicely as "Some project title / Some document title".

However both directory name Some project title and file name Some document title.md are discouraged due to whitespace and capitalization, and feel strange when working with the command line or looking at my Git repository. Also the URL has to escape the whitspace: http://localhost:3000/Some%20project%20title/Some%20document%20title

I would prefer to name all directories and files lower case and without discouraged characters:

some_project_title
  some_document_title.md

This however would today be displayed as "some_project_title / some_document_title". Maybe this would be fine, but it feels like code and not like natural language usually shown in documentation. In my optinion URL would be nicer without spaces as well: http://localhost:3000/some_project_title/some_document_title

Proposed solution

Optionally allow to change display names of directories and files either generically by convention or explicitly per resource.

Change display name by convention

Convention could be the following:

1. Capitalize the first letter
2. Replace all _ with spaces

In my example this would be enought to display filesystem structure

some_project_title
  some_document_title.md

as "Some project title / Some document title".

This display name convention could be enabled via .madness.yml, e.g.:

display_name_convention: true

Change display name by explicit override

Lets say we want to display:

http_request
  post.md

By convention this would be shown as "Http request / Post". But lets assume instead we would like to show "HTTP request / POST". We could allow to override display names of specific files and directories by defining additional metadata.

For changing diplay name of a directory we introduce a file .madness_meta.yml:

http_request
  .madness_meta.yml
  post.md

.madness_meta.yml can be as simple as:

title: HTTP request

For changing display name of a file we allow to set title via HTML comment similar to <!--TOC-->. E.g. in post.md:

<!--title:POST-->

# POST requests

This adds complexity but ideally for the authors most files and directories do not require any explicit override and already work fine just by applying the convention.

Explicit overrides could be enabled via .madness.yml, e.g.:

display_name_overrides: true

Hi.

It would help to support via environment variable the use of a subpath for reverse proxies, so you can access madness under http://server/documentation, mainly for Docker containers.

Right now it only works if used at root domain (http://server/) or in a subdomain (http://documentation.server/), because the assets are loaded from /

I tried with Caddy v2.

It would be nice if captions receive anchors, so that internal TOC links can work.

Need to see if the current renderer we use supports this out of the box.

This can probably done with ease by giving special treatment to folders and files that start with numbers followed by a dot. We can probably just hide these numbers from the link label.

Hi.

Updated to latest 1.1.3 docker version and it fails to start:
`Sinatra could not start, the "rackup" gem was not found!

Add it to your bundle with:

bundle add rackup

or install it with:

gem install rackup`

Is anything missing on my end?

The GraphViz dot integration was removed in #39

The self-proposed approach would be to do one of these:

1. Extract all diagram handling to a new gem. This will require adding plugin functionality to madness.
2. Convert the current dot handling code to a more generic, configurable handler with some magic like { from: 'dot', to: 'png', with: 'command to run' }
3. Enable the diagramming only in the docker version. An attempt at this was made, but due to Vagrant file watching issues, it is not working well (at least not in a Vagrant-based environment).

I configured a madness service behind a proxy with additional route /doc (http://proxy/doc)

madness redicted the request back to / (also missing my proxy route)

curl -v http://localhost/doc/index.md
*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to localhost (127.0.0.1) port 80 (#0)
> GET /doc/index.md HTTP/1.1
> Host: localhost
> User-Agent: curl/7.53.0
> Accept: */*
> 
< HTTP/1.1 302 Found 
< Server: nginx/1.10.2
< Date: Thu, 16 Mar 2017 18:18:04 GMT
< Content-Type: text/html;charset=utf-8
< Content-Length: 0
< Connection: keep-alive
< Location: http://localhost/index
< X-Xss-Protection: 1; mode=block
< X-Content-Type-Options: nosniff
< X-Frame-Options: SAMEORIGIN

it is possibility to configure a proxy-route into madness?

Consider adding search

Related: #51

Hi.

I tried to use a table where an entry contains a password set with ` and contains symbols, when one of the symbols of the password is a | , even it have been escaped with \ it is not taken into account and | changes to the next column.

I have attached an image of the code.

Is it possible to set somehow a piece of text in a way that is not parsed for markdown?

Hi.

I don't think this is standard but as it is being discussed here: An option to highlight a "Note" and "Warning" using blockquote (Beta) it may be of a great help to be able to highlight blocks of notes or warnings.

Hi.

First of all nice Work and it is very hulpfull.

The Topic:

$ alias madness='docker run --rm -it -v $PWD:/docs -p 3000:3000 dannyben/madness'

I use Windows 10 and have WSL2 configured in my Docker-Desktop.

My goal is to have a Theme/CSS File to make or use a Dark-Theme.

A have no "alias" command in Powershell or the CMD.

Do I miss something or is it not possible to use Powershell?

BTW: I just started to use Docker at all, and my Linux skills are way below avarage. :)

I tried to use the main.css File, but it doesn´t work.

I manually exported a default Theme, but it wasn´t applied when I used the "docker run " command.
I think I have a wrong Syntax to pass the Theme into the Container.

Could please someone explain a "Noob" how to get a Theme in Docker-Desktop via a Powershell?

thx in advance and I love You all... Wow, I just realized how my exitment for Docker and "Madness", made me "mad" lol

c.u. and greetings from Hamburg, Germany.

Consider removing options like --no-sidebar and --no-auto-nav from the command line.

The rationale: When creating custom themes, these options don't always make sense, while other theme options might be desired.

Perhaps instead of these, allow:

1. Specifying any arbitrary option in the config file
2. Allow --config FILE in the CLI, so we can still run madness with different options by using different commands.

It would be nice if we can allow theme customization, like so:

1. By default, we use the default theme
2. If there is a ~/.madness/theme folder - we will use it instead
3. If the configuration file (or CLI) specify theme: some/folder - we will use this instead

Also, we could probably do something like $ madness theme-init in the CLI, and it will copy the default theme to the current directory, as a baseline.

Maybe font awesome?

Line 10 here:

does not belong here. It should only be forced to 100vh when there is no sidebar.

This has no visible effect, but its wrong nonetheless.

Maybe something like $ madness --toc which will generate a single markdown file somewhere.

Without sidebar mostly

I am thinking about using Madness to render internal documentation stored in a Git repository. One thing I am missing at the moment is an easy way to go from the rendered page in Madness to the Markdown source code on my Git server.

For example when I am on the "Old Galactic Republic" page in Madness I would like to see a "Source" link to:
https://github.com/DannyBen/madness/blob/master/sample/Old%20Galactic%20Republic/README.md?plain=1

I have multiple use cases for this:

• Make it clear which file needs to be modified in order to change the current page
• Looking at the file history
• Doing a blame

I could imagine providing a pattern with a placeholder in .madness.yml that specifies how to create links from the relative path of served files:

# enable adding links to Markdown source files
source_link: true

# link to source in a GitHub repo 
source_link_pattern: https://github.com/DannyBen/madness/blob/master/sample/#{path}?plain=1

# link to source in a BitBucket repo
source_link_pattern: https://example.com/projects/DEMO/repos/demo/browse/#{path}?useDefaultHandler=true

The link itself could be put somewhere on the top of the page (similar to Wikipedia).

I simulated this behavior at the moment by manually adding the link on top of some of my Markdown files:

[View Source](https://github.com/DannyBen/madness/blob/master/sample/Old%20Galactic%20Republic/README.md?plain=1)

# Title

<!-- TOC -->

...

This will allow a more natural way to use folders such as files, css, images etc.

Also if we do this, then we automatically have a way to allow overriding css by placing css/main.css in the markdown folder.

HI, came across your package yesterday when I was looking for a way to serve local files (MD) on a server. I was wondering why only some folders were visible and I'm wondering if it's possible to put a toggle for this in the .madness.yml to tell it not to ignore lowercase folders. All folder structures I have tend to be lowercase by default.

Originally posted by @danwwilson in #42 (comment)

I've let madness create a config file with madness create config. The resulting .madness.yml file is in the document root folder where all my .md files are.
Now I change port: 3000 to port: 3001 in the .yml file and restart madness, but the server still starts on port 3000.

Am I missing something or is the .yml file not actually read?

I think it would be great to add a small button on code blocks ``` to copy code to clipboard

Currently only when you request a file without to add the ".md" extension, this is correctly interpreted as a markdown file but if you add the ".md" part in the url it is returned the file directly without interpret the markdown syntax.

I think that this feature should be nice to be able to have relative file references from one document to other in the same style that you could do on github for example:

* [Compilation:](./Setup/Compilation.md)

Need to sanitize HTML in the search result excerpts

What do you think about a flag to open a browser with the given URL when starting up madness?

Personally, I would find it nice if executing madness by default tries to open a browser session to visit the started sinatra app. (On a side note: another default that I personally would change is the host, where 0.0.0.0 is public, where I'd prefer 127.0.0.1, the localhost).

I have an implementation at hand (very dirty, it just forks the Server. ... call and then opens the hard-coded http://localhost:3000 via xdg-open, which might not work on other systems, but it works like a charm on mine :) ).

Not sure if this is a feature you'd consider, but I've looked at about 20 different markdown servers, and nothing beats this. I don't know ruby, so I'm looking to have madness server display links to PDFs, text files, and image files. Obviously, the only thing displayed is .md files, but I use something called https://foambubble.github.io/ as my Evernote and madness to serve the content. I have some pdfs, text files, and image files that are part of my mainly markdown notebooks, and when using madness to browse my notes, I don't see these. Would it be technically difficult to do something like this? If the link isn't to an md, wouldn't the browser render that filetype with whatever application is specified to open it?

I'd would be great to have a search field available for mobile users. Currently they have to switch to the Desktop View in order to search.

Hi,
this maybe out of scope for you but just in case you are interested I'll ask.

I really like your idea to easily serve a local folder and transform it into a nice web interface.
Since I structure each project content in a directory but not always use github to store it I was looking for an easy way to put a docker compose file in the directory and have the user start a webserver locally to have a web browsing experience of the project directory similar to GitHub.

In short was looking for a solution exactly like yours plus the current directory file browser on top (see below snapshot).
Would that be possible or do you know any other project doing something like that?

thanks

You can assign me to this task as always. ;)

Option 1:

• Add $ madness --combine flag that will generate a single Markdown file somewhere. This can then be viewed and "printed to PDF". When doing so, we will add a page break tag before each page.
• This option assumes there is no need to provide "export to PDF" option, since most systems can simply print to PDF these days.
• This will work well with #44

Option 2:

Add ability to export:

• Everything
• A folder
• A single file

And save as:

• A single HTML or PDF
• Multiple HTMLs or PDFs

This should be an easy fix here:

We should probably mimic the behavior of GitHub Pages, to show index.md instead of showing README.md, if it is found.

When browsing to a folder with one file only, and no README - maybe show it directly instead of showing the index with the only link.

markdown table syntax show correct in other markdown editor.
but have no effect in madness.

The port and bind cannot take effect from .madness.yml

(base) user docs % madness -v
1.1.0
(base) user docs % madness config show
                path:  .
                port:  3001  <-
                bind:  127.0.0.1  <-
            base_uri:  ~
             sidebar:  true
             auto_h1:  ~
            auto_nav:  ~
            auto_toc:  true
         highlighter:  true
           copy_code:  true
          shortlinks:  ~
                 toc:  ~
               theme:  ~
                open:  ~
                auth:  ~
           auth_zone:  Restricted Documentation
   expose_extensions:  ~
             exclude:  ["^[a-z_\\-0-9]+$"]

Values in blue loaded from .madness.yml
(base) user docs % madness server
▌ starting server
▌ env    : production
▌ listen : 0.0.0.0:3000  <-
▌ path   : /Users/user/docs
▌ config : .madness.yml

== Sinatra (v3.0.4) has taken the stage on 3000 for development with backup from Puma
Puma starting in single mode...
* Puma version: 6.1.1 (ruby 3.2.0-p0) ("The Way Up")
*  Min threads: 0
*  Max threads: 5
*  Environment: development
*          PID: 21842
* Listening on http://0.0.0.0:3000  <-
Use Ctrl-C to stop
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-03-09 22:43:36 +0800 ===
- Goodbye!
== Sinatra has ended his set (crowd applauds)

Related #50

Nice to see a simple project that serves markdown files as html <3

I'm looking for something like this, with two additions. If you're not familiar with Obsidian and "Zettelkasten" style smart notes, this might make little sense...

• Support for the link syntax used by Obsidian and other smart-note applications: [[Link To .md file]] is used explicitly to link to other .md files in the same directory (or subdirectory). [reddit.com](https://reddit.com] style links are still used for non-internal links.
• Support for backlink information. It would be awesome to have a list of other .md files listed that does link back to the current .md file I'm looking at. This could be a panel on the right side.

Would you be generally interested in this?

I'm not a ruby dev but I did have a brief look at your code - sadly I couldn't find any markdown parsing. Are you offloading that to another library?

From an assets folder. Needs #9