madness 0.9.9 → 1.0.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e5aec00c5e1b2645ddd8df0791c72f1f9b1dac802bf9f8ebbec7ee82adf9af3
-  data.tar.gz: b4813953be6a17acc191e98b000470351849703d33def5c6b1783d8670b3bebf
+  metadata.gz: b9cba6f044834b3b940828d81932f1537e289fdb39f7c4b6c91d5941b1fc441b
+  data.tar.gz: 5d281aa6e131eda5c3f41622b34d2c82ea57ff93677de035c4e55475988c5d28
 SHA512:
-  metadata.gz: 4ea3389d117c99fae165537c8bd6f9b6702faded54d20ca3100bb543b5f137d3643573baa1186a62cc65acc772513824a1de88a73610eef3c6817675f7cff462
-  data.tar.gz: acf4925d81080002ff39c295ec0dcb78dcdd8ee8e3b306893be27ca1be4858481552bdb09756b89b6e76c6fca91bcf5512a9c9c75d59d25662400d3ead725587
+  metadata.gz: 3ecf906622256765245b7a5b5955aab19e6abd26cec1d63cb7a578add0880ade75b4ba2cb27638db9c2e45300ec57f064057ce4bc5cbb113001ba81e9e6aa00a
+  data.tar.gz: 90bba0e9ac05b6674e1691761f319e7dac8cfb9c9d2999ed428753ddad3e4facf288540d441f23e647513c077861c4431404cd75d933c9d7f36f14a1f9475f4b

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,20 @@
 
 ---
 
-## 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 -->
+
+
+> Note: This documentation refers to the 1.0.0 pre-release version  
+> See [documentaton for v0.9.9](https://github.com/dannyben/madness/tree/v0.9.9#readme)
+> if you are using an earlier version
+
+## Screenshots
+
+[![Screenshots](assets/screenshots.gif)](assets/screenshots.gif)
 
 ## Install
 
@@ -56,11 +44,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,16 +52,20 @@ 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
 
 Go to any directory that contains markdown files and run:
 
 ```shell
-$ madness
+$ madness server
 ```
 
 And open <http://localhost:3000> in your browser.
@@ -93,14 +80,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 +106,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 config new
+```
+
+which will generate this file, with all the default options:
 
 ```yaml
 # .madness.yml
@@ -144,12 +139,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
 
@@ -172,7 +169,7 @@ open: false
 auth: false
 
 # if auth is enabled, specify auth realm name
-auth_zone: Madness
+auth_zone: Restricted Documentation
 
 # show files with these extensions in the navigation and search, for example:
 # expose_extensions: pdf,docx,xlsx,txt
@@ -183,17 +180,13 @@ expose_extensions: ~
 exclude: ['^[a-z_\-0-9]+$']
 ```
 
-For convenience, you can generate a template config file by running:
-
-```shell
-$ madness create config
-```
+## Features
 
-## 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 +209,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 +260,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 +273,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 +286,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.
 
@@ -313,7 +311,7 @@ Madness comes with a command that copies the default theme to a folder of
 your choice, where you can customize it to your taste. Run:
 
 ```shell
-$ madness create theme my_theme
+$ madness theme full my_theme
 ```
 
 Where `my_theme` is the folder that will be created.
@@ -322,7 +320,7 @@ To use the created theme, simply run Madness with the `--theme my_theme`
 option.
 
 ```shell
-$ madness --theme my_theme
+$ madness server --theme my_theme
 ```
 
 Note that the generated theme contains the SCSS files in the `styles`
@@ -336,14 +334,15 @@ any tool to do so, or if you do not have a preference, use
 
 ### Option 2: Change CSS only
 
-If you are looking to implement a smaller CSS change, follow these steps:
+If you are looking to implement a smaller CSS change, run:
+
+```shell
+$ madness theme css
+```
 
-- Create a directory named `css` in your root documentation directory.
-- Copy the [main.css][css] file to it.
-- Update it as you see fit.
+This will create the file `css/main.css` in the current directory. Update the
+file as you see fit.
 
-Note that this functionality is not guaranteed to stay as is in future 
-versions of madness.
 
 ## Docker Image
 
@@ -353,7 +352,7 @@ This command will start the server on localhost:3000, with the current
 directory as the markdown documentation folder
 
 ```shell
-$ docker run --rm -it -v $PWD:/docs -p 3000:3000 dannyben/madness
+$ docker run --rm -it -v $PWD:/docs -p 3000:3000 dannyben/madness server
 ```
 
 You may create an alias for convenience:
@@ -374,7 +373,6 @@ For more information about the docker image, see:
 
 [dockerhub]: https://hub.docker.com/r/dannyben/madness/
 [dockerfile]: https://github.com/DannyBen/docker-madness
-[css]: app/public/css/main.css
-[app]: app
+[css]: https://github.com/DannyBen/madness/blob/master/app/public/css/main.css
 [sasstool]: https://github.com/DannyBen/sasstool