From cf5953c55b6d8bd27508aaada5b090fdfa6b490f Mon Sep 17 00:00:00 2001 From: xnacly <47723417+xNaCly@users.noreply.github.com> Date: Tue, 25 Apr 2023 12:49:04 +0200 Subject: [PATCH] doc: regenered rendered documentation --- doc/index.html | 187 +++++++++++++++++++++++++++---------------------- 1 file changed, 104 insertions(+), 83 deletions(-) diff --git a/doc/index.html b/doc/index.html index 907e107..8c84ea9 100644 --- a/doc/index.html +++ b/doc/index.html @@ -6,9 +6,14 @@ --gray: #d0d7de; --light-gray: #f2f1f1; --lighter-gray: #f3f2f2; - --info: #0969da; - --warning: #ccb700; - --danger: #ff0400; + --info: rgb(2, 122, 255); + --info-lighter: rgba(2, 122, 255, 0.1); + --warning: rgb(224, 220, 0); + --warning-lighter: rgba(224, 222, 113, 0.2); + --danger: rgb(251, 70, 76); + --danger-lighter: rgba(251, 70, 76, 0.1); + --note: rgb(83, 223, 221); + --note-lighter: rgb(83, 223, 221, 0.2); } * { box-sizing: border-box; @@ -84,28 +89,44 @@ padding-right: 2rem; padding-left: 1.25rem; margin: 0; - margin-top: 0.5rem; - margin-bottom: 0.5rem; + margin-top: 1rem; + margin-bottom: 1rem; border-top-right-radius: 0.2rem; border-bottom-right-radius: 0.2rem; } blockquote .warning { color: var(--warning); } -blockquote .warning:before { - margin-right: 0.25rem; -} blockquote .info { color: var(--info); } -blockquote .info:before { - margin-right: 0.25rem; -} blockquote .danger { color: var(--danger); } -blockquote .danger:before { - margin-right: 0.25rem; +blockquote .note { + color: var(--note); +} +.callout { + padding: 1rem; + border-radius: 0.25rem; + color: black; +} +.blockquote-info { + border: 0; + background-color: var(--info-lighter); +} +.blockquote-danger { + border: 0; + background-color: var(--danger-lighter); +} +.blockquote-warning { + border-radius: 0.5rem; + border: 0; + background-color: var(--warning-lighter); +} +.blockquote-note { + border: 0; + background-color: var(--note-lighter); } hr { height: 0.15rem; @@ -144,39 +165,39 @@ strong { font-weight: 600; } -

Table of contents

Web documentation for Fleck

Source for this document, link +

Table of contents

Web documentation for Fleck

Source for this document, link

fleck - Markdown-parser

Fleck is intended for outputting standalone html from a markdown source.

Feature overview: -

Install

From source

git clone https://github.com/xnacly/fleck
+
  •  syntax highlighting
  •  custom alert blockquotes
  •  watch mode for recompiling the html if the source changed
  •  live-preview in the browser for recompiling the html and reloading the tab if the source changed
Install
From source
git clone https://github.com/xnacly/fleck
 cd fleck
 go build
-
From release
Until a release is ready please build from source.
-
Using fleck:
 Read more about fleck's usage here
  •  Follow the guide above for installing fleck
  •  Run fleck from the cli on a Markdown file of your choice, for example the README of this project:
fleck README.md
-
  •  View the output:
      Readme.png
Features
Example
View the source for the test.md file here.
+

From release

Until a release is ready please build from source. +

Using fleck:

Read more about fleck's usage here

fleck README.md
+

Features

Example

View the source for the test.md file here.

Compiled using fleck: -

fleck -preprocessor-enabled -toc -toc-full -shell-macro-enabled -syntax test.md
+
fleck -preprocessor-enabled -toc -toc-full -shell-macro-enabled -syntax test.md
 # 2023/04/19 09:31:04 warn: 'shell-macro-enabled' flag specified, this can harm your operating system and make it vulnerable for attack, proceed at your own digression
 # 2023/04/19 09:31:04 info: preprocessor enabled, starting...
 # 2023/04/19 09:31:04 warn: found @shell macro: '@shell{whoami}', executing 'whoami'
 # 2023/04/19 09:31:04 info: executed 'whoami' command
 # 2023/04/19 09:31:04 info: preprocessor finished, took 6.092121ms
 # 2023/04/19 09:31:04 info: compiled 'test.md.fleck', took: 10.278704ms
-
This spits out the following:
+

This spits out the following:

full_readme

Markdown

Fleck implements the basic markdown features everyone needs, while extending markdown with the fleck dialect, which introduces several macros.

Extra features

Blockquotes:

Fleck supports blockquotes with titles. To specify a title for a blockquote, format it as follows: -

> **Title**
+
> **Title**
 >
 > text
-
Fleck extracts the Title in the first line of the blockquote between ** and **.
+

Fleck extracts the Title in the first line of the blockquote between ** and **. After that all supported titles are colored and prefixed with a matching emoji.

Currently supported are: -

Example: +

Example:

blockquotes_fleck

Fleck's features

Usage

Overview

fleck is called like so: -

# fleck [options] file
+
# fleck [options] file
 fleck README.md
-
This command creates a file called README.html, which includes the generated html output.
+

This command creates a file called README.html, which includes the generated html output.

Help

Calling fleck with the --help flag will produce the following output: -

Usage:
+
Usage:
     fleck [Options] file
 
 Options:
@@ -199,10 +220,10 @@
         --port                  12345           live-preview            specify the port for '--live-preview' to be served on
 
 Online documentation: https://github.com/xnacly/fleck
-
See Macros for more information about the preprocessor and macros.
-
Command line option reference
`--help`
Prints the help page, containing the name of all available options, their default values, which other option they require and a description.
+

See Macros for more information about the preprocessor and macros. +

Command line option reference

--help

Prints the help page, containing the name of all available options, their default values, which other option they require and a description.

A short help is printed if fleck is called without any arguments: -

$ fleck
+
$ fleck
 Usage:
     fleck [Options] file
 
@@ -210,39 +231,39 @@
 
 2023/04/24 10:14:35 error: not enough arguments, specify an input file
 exit status 1
-
`--watch`
The watch option makes fleck watch for changes in the specified source file:
-
$ fleck --watch README.md
+
--watch
The watch option makes fleck watch for changes in the specified source file:
+
$ fleck --watch README.md
 2023/04/24 10:16:13 info: compiled 'README.md', took: 262.228µs
 2023/04/24 10:16:13 info: watching for changes...
-
Fleck checks every 100ms if a change occured.
+

Fleck checks every 100ms if a change occured. When this happens the screen is cleared and fleck tells the user how many times it already recompiled the source.: -

2023/04/24 10:17:34 info: detected change, recompiling... (1)
+
2023/04/24 10:17:34 info: detected change, recompiling... (1)
 2023/04/24 10:17:34 info: compiled 'README.md', took: 500.561µs
 2023/04/24 10:17:34 info: detected change, recompiling... (2)
 2023/04/24 10:17:34 info: compiled 'README.md', took: 720.964µs
-
Fleck checks if the source file changed by comparing its last modification time and its size with the information gathered in the previous iteration.
-
`--syntax`
The --syntax flag instructs fleck to inject three assets into the generated template.
+

Fleck checks if the source file changed by comparing its last modification time and its size with the information gathered in the previous iteration. +

--syntax

The --syntax flag instructs fleck to inject three assets into the generated template. The first is the prism default css file. The second is the prism javascript source and the third is the language autoloader, which detects used languages in the generated html and automatically loads the corresponding themes. -

$ fleck --syntax README.md
+
$ fleck --syntax README.md
 2023/04/24 10:23:18 info: compiled 'README.md', took: 186.067µs
-
A code block in the resulting html, looks like the following:
-
syntax-highlighting
`--live-preview`
Just like --watch, this option tells fleck to periodically check for changes in the source file.
+

A code block in the resulting html, looks like the following: +

syntax-highlighting

--live-preview

Just like --watch, this option tells fleck to periodically check for changes in the source file. The drastic difference here is, that fleck starts a websocket connection and a webserver which serves the generated html and injects this html with a javascript script to connect the client to the server. If fleck detects a change, it recompiles the source, exactly like laid out in the --watch reference. After that fleck sends an event to the client via the websocket connection. The client reacts and reloads itself. (HMR via the injected js script is planned, this would allow us to simply use the body.innerHTML directive to update the content)

Fleck also opens a tab supplied with the served html in the default browser of the operating system upon starting with the --live-preview flag. -

$ fleck --live-preview README.md
+
$ fleck --live-preview README.md
 2023/04/24 10:36:41 info: starting live preview
 2023/04/24 10:36:41 info: listening on http://localhost:12345/README.html
 2023/04/24 10:36:41 info: compiled 'README.md', took: 5.608431ms
 2023/04/24 10:36:41 info: watching for changes...
-
The opened tab in the default browser:
-
live-preview
`--port`
By default the --live-preview is started on port 12345, to change this behaviour invoke fleck with the --port=<port> option:
-
$ fleck --live-preview --port=12701 README.md
+
The opened tab in the default browser:
+
live-preview
--port
By default the --live-preview is started on port 12345, to change this behaviour invoke fleck with the --port=<port> option:
+
$ fleck --live-preview --port=12701 README.md
 2023/04/24 13:00:52 info: starting live preview
 2023/04/24 13:00:52 info: listening on http://localhost:12701/README.html
 2023/04/24 13:00:52 info: compiled 'README.md', took: 2.527078ms
 2023/04/24 13:00:52 info: watching for changes...
-
`--debug`
Debug simply enables more logs:
+

--debug

Debug simply enables more logs: