madness 0.9.8 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68505dca2eb6baa5db15f96986700a20e61b8f9df6eb67e53cfe457c8710dd65
-  data.tar.gz: 0e2619328fc2eb24607f13458ea858d9c99aef4d505200b9025326ffada6b9f6
+  metadata.gz: 1fff65d25c2648df428ff0bee3c9441725ee0adb3e647ae78ddf76c128712b1a
+  data.tar.gz: 7030f19dbd401b70ac476a60189c478b7bf28c6181d0232cfc1cc84cdf0655df
 SHA512:
-  metadata.gz: d932ebc6aa366dc2c714f880a43bd2f2116db6e853cb0409b29c629aa36ee28740c0de25b88da9912e27142fa6f8d8e2cb4137331d007c7526f204482e77946c
-  data.tar.gz: 8b136b49572d6f1aeab9436baa9a675974bb345afe5232d32bb3c8a3c25c4c5af1e66139e8e1a0120562df7a564639ba4d3c118bd4244ec4ab7b0b77da6407f5
+  metadata.gz: 2bd67a18e66221371ff54fa16ea344c63e4bffbd986659dbc30e3f631a0aec730693ac1eec2161f3f542abc44743434ac2619ca7bc753565d8d530bb49c56dab
+  data.tar.gz: 49e97fddb347dac7ff540cd8649ca343a8cf756050f5e3d5c2f1c0f5e3677968b0ccfe45b7be5e9ccd5447dc68bad6a91f1e655e8a3f0ac44e28816784f5ae2c

data/README.md

@@ -1,3 +1,5 @@
+[![Madness Logo](assets/header.png)](https://github.com/dannyben/madness)
+
 # Madness - Instant Markdown Server
 
 [![Gem Version](https://badge.fury.io/rb/madness.svg)](https://badge.fury.io/rb/madness)
@@ -6,34 +8,15 @@
 
 ---
 
-## Screenshots (click to zoom)
-
-<table><tr>
-  <td><a target='_screenshot' href='assets/screen-main.png'><img src='assets/screen-main.png'/></a></td>
-  <td><a target='_screenshot' href='assets/screen-nav.png'><img src='assets/screen-nav.png'/></a></td>
-  <td><a target='_screenshot' href='assets/screen-code.png'><img src='assets/screen-code.png'/></a></td>
-  <td><a target='_screenshot' href='assets/screen-search.png'><img src='assets/screen-search.png'/></a></td>
-</tr></table>
-
-## Table of Contents
-
-* [Install](#install)
-* [Design Intentions](#design-intentions)
-* [Feature Highlights](#feature-highlights)
-* [Usage](#usage)
-* [Directory Conventions](#directory-conventions)
-* [Configuration File](#configuration-file)
-* [Search](#search)
-* [Images and Static Files](#images-and-static-files)
-* [Automatic H1](#automatic-h1)
-* [Shortlinks](#shortlinks)
-* [Table of Contents Generation](#table-of-contents-generation)
-* [Hidden Directories](#hidden-directories)
-* [Controlling Sort Order](#controlling-sort-order)
-* [Displaying Additional File Types](#displaying-additional-file-types)
-* [Basic Authentication](#basic-authentication)
-* [Customizing Theme](#customizing-theme)
-* [Docker Image](#docker-image)
+Madness is a command line server for rendering markdown documents in your
+browser. It is designed to facilitate easy development of internal
+markdown-based documentation site.
+
+<!-- MADNESS_TOC -->
+
+## Screenshots
+
+[![Screenshots](assets/screenshots.gif)](assets/screenshots.gif)
 
 ## Install
 
@@ -56,11 +39,6 @@ $ brew gem install madness
 $ alias madness='docker run --rm -it -v $PWD:/docs -p 3000:3000 dannyben/madness'
 ```
 
-## Design Intentions
-
-Madness was designed in order to provide easy browsing, viewing and 
-searching for local, markdown based documentation directories.
-
 ## Feature Highlights
 
 - Easy to use.
@@ -69,9 +47,13 @@ searching for local, markdown based documentation directories.
 - Configure with a configuration file or command arguments.
 - Fully customizable theme.
 - Automatic generation of navigation sidebar.
-- Automatic generation of Table of Contents (site-wide and inline).
-- Can optionally show additional file types in the navigation menu (e.g. PDF files).
+- Automatic generation of Table of Contents (site-wide and per page).
+- Can optionally show additional file types in the navigation menu (e.g. PDF
+  files).
 - Optional support for `[[Short Link]]` syntax.
+- Optional basic authentication.
+- Support for extended markdown syntax, such as footnotes and syntax
+  highlighting.
 
 ## Usage
 
@@ -93,14 +75,14 @@ $ madness --help
 
 Madness expects to be executed in a documentation directory.
 
-A documentation directory contains only markdown files (`*.md`) and 
-sub directories that contain more markdown files.
+A documentation directory contains only markdown files (`*.md`) and sub
+directories that contain more markdown files.
 
-The server will consider the file `index.md` or `README.md` in any directory 
-as the main file describing this directory, where `index.md` has priority.
+The server will consider the file `index.md` or `README.md` in any directory as
+the main file describing this directory, where `index.md` has priority.
 
-The navigation sidebar will show all the sub directories and files in 
-the same directory as the viewed file.
+The navigation sidebar will show all the sub directories and files in the same
+directory as the viewed file.
 
 Example structure:
 
@@ -119,9 +101,17 @@ Example structure:
 
 ## Configuration File
 
-All the command line arguments can also be configured through a 
-configuration file. Create a file named `.madness.yml` in your 
-documentation directory, and modify any of the settings below.
+Madness uses sensible defaults, so therefore can be executed without configuring
+anything. Configuration is mostly done by having a file named `.madness.yml` in
+your documentation directory.
+
+For convenience, you can generate a template config file by running:
+
+```shell
+$ madness create config
+```
+
+which will generate this file, with all the default options:
 
 ```yaml
 # .madness.yml
@@ -144,12 +134,14 @@ auto_h1: true
 # append navigation to directory READMEs
 auto_nav: true
 
+# replace <!-- TOC --> in any file with its internal table of contents
+# set to true to enable it with the default '## Table of Contents' caption,
+# or set to any string that will be inserted before it as a caption.
+auto_toc: true
+
 # enable syntax highlighter for code snippets
 highlighter: true
 
-# enable line numbers for code snippets
-line_numbers: true
-
 # enable the copy to clipboard icon for code snippets
 copy_code: true
 
@@ -183,17 +175,13 @@ expose_extensions: ~
 exclude: ['^[a-z_\-0-9]+$']
 ```
 
-For convenience, you can generate a template config file by running:
+## Features
 
-```shell
-$ madness create config
-```
-
-## Search
+### Search
 
 Madness comes with a full text search page.
 
-## Images and Static Files
+### Images and Static Files
 
 You can put images and other asset files anywhere in your documentation
 folder.
@@ -216,33 +204,38 @@ the path relative to the homepage:
 ![alt text](/images/nice-picture.png)
 ```
 
-## Automatic H1
+### Automatic H1
 
 If your markdown document does not start with a level 1 heading, it
 will be automatically added based on the file name.
 
-## Shortlinks
+### Shortlinks
 
 When the `shortlinks` option is enabled, you may use a shorthand syntax for 
 specifying internal links, where `[[Anything]]` will be converted to
 `[Anything](Anything)`, which will then be rendered as an internal link to a
 file or a directory in the same directory as the file itself.
 
-## Table of Contents Generation
+### Table of Contents Generation
 
-### Site-wide
+#### Site-wide
 
 To generate a Table of Contents file for the entire site (for the directories
 and files), run `madness --toc FILENAME`
 
-### Inline
+#### In-page
 
 If you have long markdown documents, and you wish to add an inline Table of
 Contents for them, simply add an HTML comment `<!-- TOC -->` where you want
 the Table of Contents to be generated. The inserted list will only consider
 H2 and H3 headings.
 
-## Hidden Directories
+Note that for this feature to work, your markdown document must use the #-based
+heading syntax.
+
+The 'Table of Contents' heading can be customized in the configuration file.
+
+### Hidden Directories
 
 Directories that are made only of lowercase letters, underscoes, dash and/or
 numbers (`/^[a-z_\-0-9]+$/`) will not be displayed in the navigation. In
@@ -262,7 +255,7 @@ exclude: [assets, public]
 exclude: ['^public$', 'assets']
 ```
 
-## Controlling Sort Order
+### Controlling Sort Order
 
 To control the sort order of the automatically generated navigation elements,
 simply prefix your files and directories with digits followed by a dot and a 
@@ -275,7 +268,7 @@ will be omitted when they are displayed.
 └── 2. Another file or folder
 ```
 
-## Displaying Additional File Types
+### Displaying Additional File Types
 
 If you wish the navigation and search features to also show other documents
 and files (for example, PDF files), you may configure the `expose_extensions`
@@ -288,7 +281,7 @@ expose_extensions: pdf,docx,xlsx,txt
 
 The default value of this option is `null` (or `~`, which is `null` in YAML).
 
-## Basic Authentication
+### Basic Authentication
 
 To add basic authentication, use the `--auth user:password` command line argument or the equivalent `auth` configuration option.