Add more detailled documentation

author: Nicolas Paul <n@nc0.fr> 2023-04-27 00:09:29 +0200
committer: Nicolas Paul <n@nc0.fr> 2023-04-27 00:09:29 +0200
commit: e73ab4a851989e8f0dcfbb0a52c4ad75f63883da (patch)
tree: 079d874fb7d4d55e9148f5bf0fa8934c5f2e4070
parent: a2a376fe38157ee111a9ce3070179f9951672f87 (diff)
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
new 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
new 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
new 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
new 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
new 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:
+
+![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 <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:
+
+![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 <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
author	Nicolas Paul <n@nc0.fr>	2023-04-27 00:09:29 +0200
committer	Nicolas Paul <n@nc0.fr>	2023-04-27 00:09:29 +0200
commit	e73ab4a851989e8f0dcfbb0a52c4ad75f63883da (patch)
tree	079d874fb7d4d55e9148f5bf0fa8934c5f2e4070
parent	a2a376fe38157ee111a9ce3070179f9951672f87 (diff)