From e73ab4a851989e8f0dcfbb0a52c4ad75f63883da Mon Sep 17 00:00:00 2001 From: Nicolas Paul Date: Thu, 27 Apr 2023 00:09:29 +0200 Subject: Add more detailled documentation --- doc/src/.crocc.html | 5 +- doc/src/assets/doc_input_directory.png | Bin 0 -> 111456 bytes doc/src/assets/emoji_crocodile.ico | Bin 0 -> 4286 bytes doc/src/assets/example_dist.png | Bin 0 -> 19991 bytes doc/src/assets/example_index.png | Bin 0 -> 34283 bytes doc/src/assets/example_output_directory.png | Bin 0 -> 89788 bytes doc/src/doc/cli.md | 79 ++++++++++++++++++ doc/src/doc/index.md | 2 + doc/src/doc/iodir.md | 44 +++++++--- doc/src/doc/markdown.md | 119 +++++++++++++++++++++++++--- doc/src/doc/template.md | 106 +++++++++++++++++++++---- doc/src/example.md | 119 ++++++++++++++++++++++++++++ doc/src/index.md | 36 ++------- 13 files changed, 440 insertions(+), 70 deletions(-) create mode 100644 doc/src/assets/doc_input_directory.png create mode 100644 doc/src/assets/emoji_crocodile.ico create mode 100644 doc/src/assets/example_dist.png create mode 100644 doc/src/assets/example_index.png create mode 100644 doc/src/assets/example_output_directory.png create mode 100644 doc/src/doc/cli.md create mode 100644 doc/src/example.md diff --git a/doc/src/.crocc.html b/doc/src/.crocc.html index 6758f7f..460d7c3 100644 --- a/doc/src/.crocc.html +++ b/doc/src/.crocc.html @@ -33,9 +33,8 @@ - - + +
diff --git a/doc/src/assets/doc_input_directory.png b/doc/src/assets/doc_input_directory.png new file mode 100644 index 0000000..9274a97 Binary files /dev/null and b/doc/src/assets/doc_input_directory.png differ diff --git a/doc/src/assets/emoji_crocodile.ico b/doc/src/assets/emoji_crocodile.ico new file mode 100644 index 0000000..16b28a5 Binary files /dev/null and b/doc/src/assets/emoji_crocodile.ico differ diff --git a/doc/src/assets/example_dist.png b/doc/src/assets/example_dist.png new file mode 100644 index 0000000..2645ae4 Binary files /dev/null and b/doc/src/assets/example_dist.png differ diff --git a/doc/src/assets/example_index.png b/doc/src/assets/example_index.png new file mode 100644 index 0000000..711d156 Binary files /dev/null and b/doc/src/assets/example_index.png differ diff --git a/doc/src/assets/example_output_directory.png b/doc/src/assets/example_output_directory.png new file mode 100644 index 0000000..ef48877 Binary files /dev/null and b/doc/src/assets/example_output_directory.png differ diff --git a/doc/src/doc/cli.md b/doc/src/doc/cli.md new file mode 100644 index 0000000..b4aa7ba --- /dev/null +++ b/doc/src/doc/cli.md @@ -0,0 +1,79 @@ +--- +title: CLI +description: Crocc is a simple and fast static-site generator based on Markdown. +keywords: + - crocc + - markdown + - html + - go + - golang + - static + - site + - generator + - ssg + - website + - simple +publication_time: 2023-04-27T00:07:00Z +author: Nicolas Paul +--- +# CLI + +Crocc is a command-line tool. +It accepts various flags to customize its behavior. + +## Usage + +```bash +$ crocc [flags] [input directory] +``` + +## Input directory + +The `[input directory]` argument is the path to the +[input directory](/doc/iodir#input-directory) containing the files used to +build the site. + +## Flags + +Flags are used to customize the behavior of Crocc. + +### `-out` + +The `-out` flag is used to specify the +[output directory](/doc/iodir#output-directory). + +If not specified, it defaults to `./dst`. + +### `-version` + +The `-version` flag is used to print the current version of Crocc. +If specified, Crocc will print its version and exit. +The version string is formatted as: + +```go +fmt.Sprintf("crocc version %s %s/%s %s date %s", + version, runtime.GOOS, runtime.GOARCH, runtime.Compiler, date) +``` + +See the `versionFormat()` function in the +[crocc.go](https://github.com/n1c00o/crocc/blob/master/crocc.go#L55-L59) file +for the exact implementation. + +### `-help` + +The `-help` flag is used to print the help message and exit. + +### `-hidden` + +The `-hidden` flag is used to build all Markdown files, even those with +`hide: true` in their front matter. + +See the [front matter](/doc/markdown#hidden-documents) documentation for more +information. + +### `-url` + +The `-url` flag is used to specify the hostname of the site, e.g. +`-url="https://example.com"`. +It can be used inside templates through the `{{ .Site }}` variable. + diff --git a/doc/src/doc/index.md b/doc/src/doc/index.md index d01420b..824edef 100644 --- a/doc/src/doc/index.md +++ b/doc/src/doc/index.md @@ -14,10 +14,12 @@ keywords: - website - simple publication_time: 2023-04-26T19:00:00Z +publication_time: 2023-04-27T00:09:00Z author: Nicolas Paul --- # Documentation +- [CLI reference](/doc/cli) - [Markdown syntax](/doc/markdown) - [Template syntax](/doc/template) - [Input/output directory](/doc/iodir) diff --git a/doc/src/doc/iodir.md b/doc/src/doc/iodir.md index 6010ad4..6cb0017 100644 --- a/doc/src/doc/iodir.md +++ b/doc/src/doc/iodir.md @@ -14,21 +14,45 @@ keywords: - website - simple publication_time: 2023-04-26T19:00:00Z +publication_time: 2023-04-26T23:57:43Z author: Nicolas Paul --- # Input/output directory -The input directory is the directory containing the various files used to -build the site. -The input directory must contain a `.crocc.html` file, which is the -template used to generate the HTML pages. +Crocc requires two directories to work: the input directory and the output +directory. + +## Input directory + +The input directory is a folder containing all the files used to build the +site. +At its root, it should contain a `.crocc.html` file, which is the +[template file](/doc/template). > Only the top-level template is used. Nested templates are not supported. -The output directory is the directory where the generated HTML files will be -written. -The output directory must not exist before running Crocc. +Each Markdown file in this directory will be transformed to an HTML file. +Other files will be copied as-is to the output directory. + +For illustration, here is a sample input directory: + +![Sample input directory](/assets/doc_input_dir.png) + +## Output directory + +The output directory is a folder containing the generated site. +It is created by Crocc if it does not exist. + +> Crocc will not delete the output directory if it already exists. +> Instead, it will exit. + +The output directory is defined at compile time by using the `-out` +[flag](/doc/cli#flags). If not specified, it defaults to `./dst`. + +Here is the output directory corresponding to the previous input directory: + +![Sample output directory](/assets/doc_output_dir.png) -Crocc will copy all the files in the input directory to the output directory, -except the `.crocc.html` file. -During the copy, Crocc will transform Markdown documents to HTML files. \ No newline at end of file +As you can see, the output directory contains the same files as the input +directory, except for the template file and the Markdown files, which have been +converted to HTML documents. diff --git a/doc/src/doc/markdown.md b/doc/src/doc/markdown.md index 37a62b3..a3ea021 100644 --- a/doc/src/doc/markdown.md +++ b/doc/src/doc/markdown.md @@ -14,26 +14,107 @@ keywords: - website - simple publication_time: 2023-04-26T19:00:00Z +last_update_time: 2023-04-27T00:04:00Z author: Nicolas Paul --- # Markdown document +A Markdown document is a file whose extension is either `.md`, `.markdown`, +`.mdown` or `.Markdown`. + +Markdown documents are used to generate HTML documents. +They should be placed in the [input directory](/doc/iodir#input-directory). +At the top of the Markdown document, there must be a YAML header. +See the [front matter](#front-matter) section for more information. + +## Markdown syntax + +Crocc uses [`github.com/gomarkdown/markdown`](https://github.com/gomarkdown/markdown) +(*GoMarkdown*) to parse Markdown documents. + +GoMarkdown is a Markdown parser written in Go that supports various Markdown +extensions. +By default, GoMarkdown supports the CommonMark specification. + +Crocc also uses the following extensions of GoMarkdown: + +```go +extensions := parser.Tables | parser.FencedCode | + parser.Autolink | parser.Strikethrough | parser.SpaceHeadings | + parser.HeadingIDs | parser.BackslashLineBreak | + parser.AutoHeadingIDs | parser.Footnotes | parser.SuperSubscript | + parser.NoIntraEmphasis +``` + +- `parser.Tables` enables the parsing of tables similar to the ones in + [GitHub Flavored Markdown](https://github.github.com/gfm/#tables-extension-). +- `parser.FencedCode` enables the parsing of fenced code blocks and generating + HTML `` tags to help with syntax highlighting. +- `parser.Autolink` enables the parsing of URLs that are not explicitly marked. +- `parser.Strikethrough` enables the parsing of strike-through text using two + tildes (`~~test~~`). +- `parser.SpaceHeadings` makes the parser more strict about prefix heading + rules. +- `parser.HeadingIDs` enables the parsing of custom heading IDs using `{#id}`. + For instance, the following will generate a heading with the ID + `hello` instead of the default `hello-world`: + + ```md + {#hello} + # Hello World + ``` +- `parser.BackslashLineBreak` enables the parsing of trailing backslashes as + line breaks, as present in the original `Markdown.pl` implementation. +- `parser.AutoHeadingIDs` enables the generation of heading IDs from the text. + For instance, the following will generate a heading with the ID + `hello-world`: + + ```md + # Hello World + ``` +- `parser.Footnotes` enables the parsing of footnotes using the following + syntax: + + ```md + Here is a footnote reference,[^1] and another.[^longnote] + + [^1]: Here is the footnote. + [^longnote]: Here's one with multiple blocks. + + Subsequent paragraphs are indented to show that they + belong to the previous footnote. + ``` +- `parser.SuperSubscript` enables the parsing of super- and subscript text + using `^` and `~` respectively. + For illustration, the following will generate `H2O` and + `210`: + + ```md + H~2~O + 2^10 + ``` +- `parser.NoIntraEmphasis` disables the parsing of emphasis inside of words, + as in `foo_bar_baz`. + +## Front matter + The Markdown document must have a YAML header, also known as "front matter". -The YAML header is a set of key-value pairs separated by a colon. -The YAML header is followed by the Markdown document. +The YAML header is a set of key-value pairs separated by a colon, placed inside +two lines of three dashes (`---`). Front matter keys: -- `title`: The title of the document. Required. -- `description`: The description of the document. Required. -- `publication_time`: The date of the document. Required. -- `last_update_time`: The date of the last update of the document. Not required. -- `keywords`: The tags of the document, as a list of strings. Required. -- `author`: The author of the document. Default is `""`. -- `hide`: If set to `true`, the document will not be generated. - Default is `false`. +| Key | Type | Description | +| ------------------ | :-------------: | --------------------------------------------------------------------------------------- | +| `title` | string | The title of the document. Required. | +| `description` | string | The description of the document. Required. | +| `publication_time` | string | The date of the document. Required. | +| `last_update_time` | string | The date of the last update of the document. Not required. | +| `keywords` | list of strings | The tags of the document, as a list of strings. Required. | +| `author` | string | The author of the document. Default is `""`. | +| `hide` | boolean | If set to `true`, the document will be [hidden](#hidden-documents). Default is `false`. | -Example: +For instance: ```md --- @@ -48,4 +129,18 @@ hide: true # Hello World! This is a simple example of a Markdown document. -``` \ No newline at end of file +``` + +Front matter keys are used to populate the [template file](/doc/template), +thus allowing the user to customize the generated HTML document. + +## Hidden documents + +A document can be hidden by setting the `hide` key to `true` in the front +matter. +Hidden documents are not included in the generated site, unless the +[`-hidden` flag](/doc/cli#-hidden) is set. + +Hidden documents are useful for drafts (documents that are not ready to +be published yet). + diff --git a/doc/src/doc/template.md b/doc/src/doc/template.md index 522afd6..bcf4b48 100644 --- a/doc/src/doc/template.md +++ b/doc/src/doc/template.md @@ -14,29 +14,35 @@ keywords: - website - simple publication_time: 2023-04-26T19:00:00Z +last_update_time: 2023-04-27T00:07:00Z author: Nicolas Paul --- # Template file -To create HTML pages, Crocc uses a template file. +To create dynamic HTML pages, Crocc uses a template file. The template file, written in HTML using Go template syntax, must be located in -the `$INPUT/.crocc.html` file. +the `.crocc.html` file at the root of the +[input directory](/doc/iodir#input-directory). -The template file is injected with a set of variables. A variable can be used -in the template file using the `{{ .VariableName }}` syntax. -Read the [Go template documentation](https: //golang.org/pkg/text/template) for +The template file is injected with a set of variables. +A variable can be used in the template file using the `{{ .VariableName }}` +syntax. +Read the [Go template documentation](https://golang.org/pkg/text/template) for more information. The following variables are available: -* `.Title`: The title of the document. -* `.Description`: The description of the document. -* `.PublicationTime`: The date of the document. -* `.LastUpdateTime`: The date of the last update of the document. -* `.Keywords`: The tags of the document, as a string separated by commas. -* `.Author`: The author of the document. -* `.Content`: The content of the document, as HTML. -* `.Site`: The URL of the site. -* `.Generator`: A string containing the name and version of the generator. +- `.Title`: The title of the document. +- `.Description`: The description of the document. +- `.PublicationTime`: The date of the document. +- `.LastUpdateTime`: The date of the last update of the document. +- `.Keywords`: The tags of the document, as a string separated by commas. +- `.Author`: The author of the document. +- `.Content`: The content of the document, as HTML. +- `.Site`: The URL of the site. +- `.Generator`: A string containing the name and version of the generator. + +> **Note:** The `.Content` variable is already HTML, so it does not need to be +> escaped. Here is a sample template: @@ -66,4 +72,76 @@ Here is a sample template: +``` + +Using templates, you can create a navigation bar, a footer, or any other +recurring element on your site. + +For illustration purposes, here is the template used for this documentation: + +```html + + + + + + + + {{ .Title }} + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ {{ .Content }} +
+
+
+ +

Copyright (c) 2023, Nicolas Paul

+
+ + ``` \ No newline at end of file diff --git a/doc/src/example.md b/doc/src/example.md new file mode 100644 index 0000000..f608f63 --- /dev/null +++ b/doc/src/example.md @@ -0,0 +1,119 @@ +--- +title: Example +description: Crocc is a simple and fast static-site generator based on Markdown. +keywords: + - crocc + - markdown + - html + - go + - golang + - static + - site + - generator + - ssg + - website + - simple +publication_time: 2023-04-27T00:08:00Z +author: Nicolas Paul +--- +# Example + +First, make sure you have Crocc installed on your system. +If not, see the [installation](/#installation) page. + +Now, let's create a new Crocc website: + +First, create a new Crocc project: + +```bash +$ mkdir my-website +``` + +The `my-website` directory will contains all the file composing the site. + +Inside this directory, create a `.crocc.html` file. +This file contains the HTML template used to generate HTML documents. +For example, you can use the following template: + +```html + + + + + {{ .Title }} + + + + + + + + {{ .Content }} + + +``` + +> More information about the template syntax can be found in the +> [template documentation](/doc/templates) page. + +Then, create a `index.md` file next to the template file. +Each Markdown file will be converted to an HTML file. + +```markdown +--- +title: My website +description: This is my website. +keywords: + - my + - website + - example +publication_time: 2023-04-26T19:05:00Z +author: John Doe +--- +# My website + +This is my website. +``` + +Every Markdown file must have a header containing metadata about the document. +This header is known as YAML front matter. More information about it are +available in the [front matter documentation](/doc/markdown) page. + +Before building the website, we need to create a `style.css` file in the +source directory. +As with other non-Markdown file, this file will be directly copied to the +output directory. + +```css +body { + font-family: sans-serif; + color: #f2c933; /* yellow-ish */ + background-color: #1f1f1f; /* dark grey */ +} +``` + +Now, we can build the website: + +```bash +$ crocc -out=dist -url="https://example.com" my-website +``` + +The `-out` flag specifies the output directory, and the `-url` flag specifies +the base URL of the website. + +The `dist` directory now contains the generated website: + +![Screenshot of the generated dist directory](/assets/example_dist.png) + +You can now serve the `dist` directory with your favorite web server. +Here is the `index.html` file generated by Crocc: + +![Screenshot of the generated index.html file](/assets/example_index.png) + +## Conclusion + +This example is very simple, but it shows the main features of Crocc. +For more information, see the [documentation](/doc) page. + +This website itself is built with Crocc, and its source code is available +[here](https://github.com/n1c00o/crocc/tree/master/doc/). diff --git a/doc/src/index.md b/doc/src/index.md index dcd98b0..ecd8d0a 100644 --- a/doc/src/index.md +++ b/doc/src/index.md @@ -14,6 +14,7 @@ keywords: - website - simple publication_time: 2023-04-26T19:05:00Z +publication_time: 2023-04-27T00:08:00Z author: Nicolas Paul --- # Crocc @@ -39,38 +40,11 @@ $ go install go.nc0.fr/crocc@latest ## Usage -Let's say you have a directory containing the following files: +See the [example](/example) for a simple example of a Crocc website. -``` -src/ -├── .crocc.html -├── index.md -├── about.md -├── bar.png -└── contact.md -``` - -The `.crocc.html` file is the template used to generate the HTML pages. -The `index.md`, `about.md` and `contact.md` files are Markdown documents. -The `bar.png` file is a static file. - -To generate the HTML files, run the following command: - -```bash -$ crocc -out=dst -url="http://example.com" src -``` - -The `dst` directory will contain the following files: - -``` -dst/ -├── index.html -├── about.html -├── bar.png -└── contact.html -``` - -You can now upload the `dst` directory to your web server and you're done! +A more concrete project is +[this website itself](https://github.com/n1c00o/crocc/tree/master/doc), which +is built with Crocc. ## Documentation -- cgit v1.2.3