madness 0.9.8 → 1.0.0.rc1

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 68505dca2eb6baa5db15f96986700a20e61b8f9df6eb67e53cfe457c8710dd65
4
- data.tar.gz: 0e2619328fc2eb24607f13458ea858d9c99aef4d505200b9025326ffada6b9f6
3
+ metadata.gz: 1fff65d25c2648df428ff0bee3c9441725ee0adb3e647ae78ddf76c128712b1a
4
+ data.tar.gz: 7030f19dbd401b70ac476a60189c478b7bf28c6181d0232cfc1cc84cdf0655df
5
5
  SHA512:
6
- metadata.gz: d932ebc6aa366dc2c714f880a43bd2f2116db6e853cb0409b29c629aa36ee28740c0de25b88da9912e27142fa6f8d8e2cb4137331d007c7526f204482e77946c
7
- data.tar.gz: 8b136b49572d6f1aeab9436baa9a675974bb345afe5232d32bb3c8a3c25c4c5af1e66139e8e1a0120562df7a564639ba4d3c118bd4244ec4ab7b0b77da6407f5
6
+ metadata.gz: 2bd67a18e66221371ff54fa16ea344c63e4bffbd986659dbc30e3f631a0aec730693ac1eec2161f3f542abc44743434ac2619ca7bc753565d8d530bb49c56dab
7
+ data.tar.gz: 49e97fddb347dac7ff540cd8649ca343a8cf756050f5e3d5c2f1c0f5e3677968b0ccfe45b7be5e9ccd5447dc68bad6a91f1e655e8a3f0ac44e28816784f5ae2c
data/README.md CHANGED
@@ -1,3 +1,5 @@
1
+ [![Madness Logo](assets/header.png)](https://github.com/dannyben/madness)
2
+
1
3
  # Madness - Instant Markdown Server
2
4
 
3
5
  [![Gem Version](https://badge.fury.io/rb/madness.svg)](https://badge.fury.io/rb/madness)
@@ -6,34 +8,15 @@
6
8
 
7
9
  ---
8
10
 
9
- ## Screenshots (click to zoom)
10
-
11
- <table><tr>
12
- <td><a target='_screenshot' href='assets/screen-main.png'><img src='assets/screen-main.png'/></a></td>
13
- <td><a target='_screenshot' href='assets/screen-nav.png'><img src='assets/screen-nav.png'/></a></td>
14
- <td><a target='_screenshot' href='assets/screen-code.png'><img src='assets/screen-code.png'/></a></td>
15
- <td><a target='_screenshot' href='assets/screen-search.png'><img src='assets/screen-search.png'/></a></td>
16
- </tr></table>
17
-
18
- ## Table of Contents
19
-
20
- * [Install](#install)
21
- * [Design Intentions](#design-intentions)
22
- * [Feature Highlights](#feature-highlights)
23
- * [Usage](#usage)
24
- * [Directory Conventions](#directory-conventions)
25
- * [Configuration File](#configuration-file)
26
- * [Search](#search)
27
- * [Images and Static Files](#images-and-static-files)
28
- * [Automatic H1](#automatic-h1)
29
- * [Shortlinks](#shortlinks)
30
- * [Table of Contents Generation](#table-of-contents-generation)
31
- * [Hidden Directories](#hidden-directories)
32
- * [Controlling Sort Order](#controlling-sort-order)
33
- * [Displaying Additional File Types](#displaying-additional-file-types)
34
- * [Basic Authentication](#basic-authentication)
35
- * [Customizing Theme](#customizing-theme)
36
- * [Docker Image](#docker-image)
11
+ Madness is a command line server for rendering markdown documents in your
12
+ browser. It is designed to facilitate easy development of internal
13
+ markdown-based documentation site.
14
+
15
+ <!-- MADNESS_TOC -->
16
+
17
+ ## Screenshots
18
+
19
+ [![Screenshots](assets/screenshots.gif)](assets/screenshots.gif)
37
20
 
38
21
  ## Install
39
22
 
@@ -56,11 +39,6 @@ $ brew gem install madness
56
39
  $ alias madness='docker run --rm -it -v $PWD:/docs -p 3000:3000 dannyben/madness'
57
40
  ```
58
41
 
59
- ## Design Intentions
60
-
61
- Madness was designed in order to provide easy browsing, viewing and
62
- searching for local, markdown based documentation directories.
63
-
64
42
  ## Feature Highlights
65
43
 
66
44
  - Easy to use.
@@ -69,9 +47,13 @@ searching for local, markdown based documentation directories.
69
47
  - Configure with a configuration file or command arguments.
70
48
  - Fully customizable theme.
71
49
  - Automatic generation of navigation sidebar.
72
- - Automatic generation of Table of Contents (site-wide and inline).
73
- - Can optionally show additional file types in the navigation menu (e.g. PDF files).
50
+ - Automatic generation of Table of Contents (site-wide and per page).
51
+ - Can optionally show additional file types in the navigation menu (e.g. PDF
52
+ files).
74
53
  - Optional support for `[[Short Link]]` syntax.
54
+ - Optional basic authentication.
55
+ - Support for extended markdown syntax, such as footnotes and syntax
56
+ highlighting.
75
57
 
76
58
  ## Usage
77
59
 
@@ -93,14 +75,14 @@ $ madness --help
93
75
 
94
76
  Madness expects to be executed in a documentation directory.
95
77
 
96
- A documentation directory contains only markdown files (`*.md`) and
97
- sub directories that contain more markdown files.
78
+ A documentation directory contains only markdown files (`*.md`) and sub
79
+ directories that contain more markdown files.
98
80
 
99
- The server will consider the file `index.md` or `README.md` in any directory
100
- as the main file describing this directory, where `index.md` has priority.
81
+ The server will consider the file `index.md` or `README.md` in any directory as
82
+ the main file describing this directory, where `index.md` has priority.
101
83
 
102
- The navigation sidebar will show all the sub directories and files in
103
- the same directory as the viewed file.
84
+ The navigation sidebar will show all the sub directories and files in the same
85
+ directory as the viewed file.
104
86
 
105
87
  Example structure:
106
88
 
@@ -119,9 +101,17 @@ Example structure:
119
101
 
120
102
  ## Configuration File
121
103
 
122
- All the command line arguments can also be configured through a
123
- configuration file. Create a file named `.madness.yml` in your
124
- documentation directory, and modify any of the settings below.
104
+ Madness uses sensible defaults, so therefore can be executed without configuring
105
+ anything. Configuration is mostly done by having a file named `.madness.yml` in
106
+ your documentation directory.
107
+
108
+ For convenience, you can generate a template config file by running:
109
+
110
+ ```shell
111
+ $ madness create config
112
+ ```
113
+
114
+ which will generate this file, with all the default options:
125
115
 
126
116
  ```yaml
127
117
  # .madness.yml
@@ -144,12 +134,14 @@ auto_h1: true
144
134
  # append navigation to directory READMEs
145
135
  auto_nav: true
146
136
 
137
+ # replace <!-- TOC --> in any file with its internal table of contents
138
+ # set to true to enable it with the default '## Table of Contents' caption,
139
+ # or set to any string that will be inserted before it as a caption.
140
+ auto_toc: true
141
+
147
142
  # enable syntax highlighter for code snippets
148
143
  highlighter: true
149
144
 
150
- # enable line numbers for code snippets
151
- line_numbers: true
152
-
153
145
  # enable the copy to clipboard icon for code snippets
154
146
  copy_code: true
155
147
 
@@ -183,17 +175,13 @@ expose_extensions: ~
183
175
  exclude: ['^[a-z_\-0-9]+$']
184
176
  ```
185
177
 
186
- For convenience, you can generate a template config file by running:
178
+ ## Features
187
179
 
188
- ```shell
189
- $ madness create config
190
- ```
191
-
192
- ## Search
180
+ ### Search
193
181
 
194
182
  Madness comes with a full text search page.
195
183
 
196
- ## Images and Static Files
184
+ ### Images and Static Files
197
185
 
198
186
  You can put images and other asset files anywhere in your documentation
199
187
  folder.
@@ -216,33 +204,38 @@ the path relative to the homepage:
216
204
  ![alt text](/images/nice-picture.png)
217
205
  ```
218
206
 
219
- ## Automatic H1
207
+ ### Automatic H1
220
208
 
221
209
  If your markdown document does not start with a level 1 heading, it
222
210
  will be automatically added based on the file name.
223
211
 
224
- ## Shortlinks
212
+ ### Shortlinks
225
213
 
226
214
  When the `shortlinks` option is enabled, you may use a shorthand syntax for
227
215
  specifying internal links, where `[[Anything]]` will be converted to
228
216
  `[Anything](Anything)`, which will then be rendered as an internal link to a
229
217
  file or a directory in the same directory as the file itself.
230
218
 
231
- ## Table of Contents Generation
219
+ ### Table of Contents Generation
232
220
 
233
- ### Site-wide
221
+ #### Site-wide
234
222
 
235
223
  To generate a Table of Contents file for the entire site (for the directories
236
224
  and files), run `madness --toc FILENAME`
237
225
 
238
- ### Inline
226
+ #### In-page
239
227
 
240
228
  If you have long markdown documents, and you wish to add an inline Table of
241
229
  Contents for them, simply add an HTML comment `<!-- TOC -->` where you want
242
230
  the Table of Contents to be generated. The inserted list will only consider
243
231
  H2 and H3 headings.
244
232
 
245
- ## Hidden Directories
233
+ Note that for this feature to work, your markdown document must use the #-based
234
+ heading syntax.
235
+
236
+ The 'Table of Contents' heading can be customized in the configuration file.
237
+
238
+ ### Hidden Directories
246
239
 
247
240
  Directories that are made only of lowercase letters, underscoes, dash and/or
248
241
  numbers (`/^[a-z_\-0-9]+$/`) will not be displayed in the navigation. In
@@ -262,7 +255,7 @@ exclude: [assets, public]
262
255
  exclude: ['^public$', 'assets']
263
256
  ```
264
257
 
265
- ## Controlling Sort Order
258
+ ### Controlling Sort Order
266
259
 
267
260
  To control the sort order of the automatically generated navigation elements,
268
261
  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.
275
268
  └── 2. Another file or folder
276
269
  ```
277
270
 
278
- ## Displaying Additional File Types
271
+ ### Displaying Additional File Types
279
272
 
280
273
  If you wish the navigation and search features to also show other documents
281
274
  and files (for example, PDF files), you may configure the `expose_extensions`
@@ -288,7 +281,7 @@ expose_extensions: pdf,docx,xlsx,txt
288
281
 
289
282
  The default value of this option is `null` (or `~`, which is `null` in YAML).
290
283
 
291
- ## Basic Authentication
284
+ ### Basic Authentication
292
285
 
293
286
  To add basic authentication, use the `--auth user:password` command line argument or the equivalent `auth` configuration option.
294
287