diff options
| -rw-r--r-- | doc/src/.crocc.html | 5 | ||||
| -rw-r--r-- | doc/src/assets/doc_input_directory.png | bin | 0 -> 111456 bytes | |||
| -rw-r--r-- | doc/src/assets/emoji_crocodile.ico | bin | 0 -> 4286 bytes | |||
| -rw-r--r-- | doc/src/assets/example_dist.png | bin | 0 -> 19991 bytes | |||
| -rw-r--r-- | doc/src/assets/example_index.png | bin | 0 -> 34283 bytes | |||
| -rw-r--r-- | doc/src/assets/example_output_directory.png | bin | 0 -> 89788 bytes | |||
| -rw-r--r-- | doc/src/doc/cli.md | 79 | ||||
| -rw-r--r-- | doc/src/doc/index.md | 2 | ||||
| -rw-r--r-- | doc/src/doc/iodir.md | 44 | ||||
| -rw-r--r-- | doc/src/doc/markdown.md | 119 | ||||
| -rw-r--r-- | doc/src/doc/template.md | 106 | ||||
| -rw-r--r-- | doc/src/example.md | 119 | ||||
| -rw-r--r-- | doc/src/index.md | 36 |
13 files changed, 440 insertions, 70 deletions
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 @@ <meta property="og:site_name" content="Crocc" /> <meta property="og:image" content="{{ .Site }}/assets/crocodile.jpg" /> <link rel="stylesheet" href="/style.css"> - <link rel="shortcut icon" href="assets/emoji_crocodile.svg" - type="image/svg"> - <link rel="apple-touch-icon" href="assets/emoji_crocodile.png"> + <link rel="icon" href="assets/emoji_crocodile.ico" sizes="any"> + <link rel="mask-icon" href="assets/emoji_crocodile.svg" color="155eca"> </head> <body> <header> diff --git a/doc/src/assets/doc_input_directory.png b/doc/src/assets/doc_input_directory.png Binary files differnew file mode 100644 index 0000000..9274a97 --- /dev/null +++ b/doc/src/assets/doc_input_directory.png diff --git a/doc/src/assets/emoji_crocodile.ico b/doc/src/assets/emoji_crocodile.ico Binary files differnew file mode 100644 index 0000000..16b28a5 --- /dev/null +++ b/doc/src/assets/emoji_crocodile.ico diff --git a/doc/src/assets/example_dist.png b/doc/src/assets/example_dist.png Binary files differnew file mode 100644 index 0000000..2645ae4 --- /dev/null +++ b/doc/src/assets/example_dist.png diff --git a/doc/src/assets/example_index.png b/doc/src/assets/example_index.png Binary files differnew file mode 100644 index 0000000..711d156 --- /dev/null +++ b/doc/src/assets/example_index.png diff --git a/doc/src/assets/example_output_directory.png b/doc/src/assets/example_output_directory.png Binary files differnew file mode 100644 index 0000000..ef48877 --- /dev/null +++ b/doc/src/assets/example_output_directory.png 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 <n@nc0.fr> +--- +# 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 <n@nc0.fr> --- # 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 <n@nc0.fr> --- # 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: + + + +## 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: + + -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 <n@nc0.fr> --- # 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 `<code>` 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 `H<sub>2</sub>O` and + `2<sup>10</sup>`: + + ```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 <n@nc0.fr> --- # 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: </footer> </body> </html> +``` + +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 +<!DOCTYPE html> +<!-- + Copyright (c) 2023 Nicolas Paul All rights reserved. + Use of this source code is governed by a BSD-style + license that can be found in the LICENSE file. +--> +<html lang="en"> + <head> + <meta charset="UTF-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <title>{{ .Title }}</title> + <meta name="author" content="{{ .Author }}" /> + <meta name="description" content="{{ .Description }}" /> + <meta name="keywords" content="{{ .Keywords }}" /> + <meta name="generator" content="{{ .Generator }}"> + <meta name="color-scheme" content="light dark" /> + <meta name="theme-color" content="#155eca"> + <meta name="robots" content="all" /> + <link rel="sitemap" href="/sitemap.xml" /> + <meta name="twitter:card" content="summary_large_image" /> + <meta name="twitter:site" content="@ncs_pl" /> + <meta name="twitter:title" content="{{ .Title }}" /> + <meta name="twitter:description" content="{{ .Description }}" /> + <meta name="twitter:image" content="{{ .Site }}/assets/crocodile.jpg" /> + <meta property="og:title" content="{{ .Title }}" /> + <meta property="og:type" content="website" /> + <meta property="og:url" content="{{ .Site }}" /> + <meta property="og:description" content="{{ .Description }}" /> + <meta property="og:determiner" content="" /> + <meta property="og:locale" content="en" /> + <meta property="og:site_name" content="Crocc" /> + <meta property="og:image" content="{{ .Site }}/assets/crocodile.jpg" /> + <link rel="stylesheet" href="/style.css"> + <link rel="icon" href="assets/emoji_crocodile.ico" sizes="any"> + <link rel="mask-icon" href="assets/emoji_crocodile.svg" color="155eca"> + </head> + <body> + <header> + <nav> + <ul> + <li><strong>Crocc</strong></li> + <li><a href="/">Home</a></li> + <li> + <a href="https://github.com/n1c00o/crocc" + target="_blank">Source</a> + </li> + <li> + <a href="https://nc0.fr" target="_blank">Nicolas + Paul</a> + </li> + </ul> + </nav> + </header> + <main> + {{ .Content }} + </main> + <footer> + <hr /> + + <p>Copyright (c) 2023, Nicolas Paul</p> + </footer> + </body> +</html> ```
\ 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 <n@nc0.fr> +--- +# 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 +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <title>{{ .Title }}</title> + <meta name="description" content="{{ .Description }}"> + <meta name="keywords" content="{{ .Keywords }}"> + <meta name="author" content="{{ .Author }}"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <link rel="stylesheet" href="/style.css"> +</head> +<body> + {{ .Content }} +</body> +</html> +``` + +> 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: + + + +You can now serve the `dist` directory with your favorite web server. +Here is the `index.html` file generated by Crocc: + + + +## 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 <n@nc0.fr> --- # 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 |
