From 8c79798252b6b09817c39b6988e096d014585455 Mon Sep 17 00:00:00 2001 From: Nicolas Paul Date: Wed, 26 Apr 2023 21:08:50 +0200 Subject: Add documentation site --- doc/src/.crocc.html | 65 ++++++++++++++++++++++++ doc/src/assets/crocodile.jpg | Bin 0 -> 3902459 bytes doc/src/assets/emoji_crocodile.png | Bin 0 -> 5594 bytes doc/src/assets/emoji_crocodile.svg | 99 +++++++++++++++++++++++++++++++++++++ doc/src/doc/index.md | 23 +++++++++ doc/src/doc/iodir.md | 34 +++++++++++++ doc/src/doc/markdown.md | 51 +++++++++++++++++++ doc/src/doc/template.md | 69 ++++++++++++++++++++++++++ doc/src/index.md | 90 +++++++++++++++++++++++++++++++++ doc/src/robots.txt | 4 ++ doc/src/sitemap.xml | 23 +++++++++ doc/src/style.css | 91 ++++++++++++++++++++++++++++++++++ 12 files changed, 549 insertions(+) create mode 100644 doc/src/.crocc.html create mode 100644 doc/src/assets/crocodile.jpg create mode 100644 doc/src/assets/emoji_crocodile.png create mode 100644 doc/src/assets/emoji_crocodile.svg create mode 100644 doc/src/doc/index.md create mode 100644 doc/src/doc/iodir.md create mode 100644 doc/src/doc/markdown.md create mode 100644 doc/src/doc/template.md create mode 100644 doc/src/index.md create mode 100644 doc/src/robots.txt create mode 100644 doc/src/sitemap.xml create mode 100644 doc/src/style.css (limited to 'doc/src') diff --git a/doc/src/.crocc.html b/doc/src/.crocc.html new file mode 100644 index 0000000..574671d --- /dev/null +++ b/doc/src/.crocc.html @@ -0,0 +1,65 @@ + + + + + + + + + {{ .Title }} + + + + + + + + + + + + + + + + + + + + + + + + + +

+ +

+ {{ .Content }} +

+ + + \ No newline at end of file diff --git a/doc/src/assets/crocodile.jpg b/doc/src/assets/crocodile.jpg new file mode 100644 index 0000000..297d4de Binary files /dev/null and b/doc/src/assets/crocodile.jpg differ diff --git a/doc/src/assets/emoji_crocodile.png b/doc/src/assets/emoji_crocodile.png new file mode 100644 index 0000000..8f151c7 Binary files /dev/null and b/doc/src/assets/emoji_crocodile.png differ diff --git a/doc/src/assets/emoji_crocodile.svg b/doc/src/assets/emoji_crocodile.svg new file mode 100644 index 0000000..f9049ee --- /dev/null +++ b/doc/src/assets/emoji_crocodile.svg @@ -0,0 +1,99 @@ + + + diff --git a/doc/src/doc/index.md b/doc/src/doc/index.md new file mode 100644 index 0000000..21a70fb --- /dev/null +++ b/doc/src/doc/index.md @@ -0,0 +1,23 @@ +--- +title: Documentation +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-26T19:00:00Z +author: Nicolas Paul +--- +# Documentation + +- [Markdown syntax](/doc/markdown) +- [Template syntax](/doc/template) +- [Input/output directory](/doc/iodir.md) diff --git a/doc/src/doc/iodir.md b/doc/src/doc/iodir.md new file mode 100644 index 0000000..6010ad4 --- /dev/null +++ b/doc/src/doc/iodir.md @@ -0,0 +1,34 @@ +--- +title: Input/output directory +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-26T19:00:00Z +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. + +> 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. + +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 diff --git a/doc/src/doc/markdown.md b/doc/src/doc/markdown.md new file mode 100644 index 0000000..37a62b3 --- /dev/null +++ b/doc/src/doc/markdown.md @@ -0,0 +1,51 @@ +--- +title: Markdown syntax +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-26T19:00:00Z +author: Nicolas Paul +--- +# Markdown document + +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. + +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`. + +Example: + +```md +--- +title: Hello World +description: This is a simple example of a Markdown document. +publication_time: 2020-01-01T00:00:00Z +last_update_time: 2020-01-01T03:00:00Z +keywords: [example, hello, world] +author: John Doe +hide: true +--- +# Hello World! + +This is a simple example of a Markdown document. +``` \ No newline at end of file diff --git a/doc/src/doc/template.md b/doc/src/doc/template.md new file mode 100644 index 0000000..522afd6 --- /dev/null +++ b/doc/src/doc/template.md @@ -0,0 +1,69 @@ +--- +title: Template file +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-26T19:00:00Z +author: Nicolas Paul +--- +# Template file + +To create 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 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. + +Here is a sample template: + +```html + + + + + {{ .Title }} + + + + + + + +

+ {{ .Content }} +

+ + + +``` \ No newline at end of file diff --git a/doc/src/index.md b/doc/src/index.md new file mode 100644 index 0000000..b5ce035 --- /dev/null +++ b/doc/src/index.md @@ -0,0 +1,90 @@ +--- +title: Crocc +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-26T19:05:00Z +author: Nicolas Paul +--- +# Crocc + +Crocc is a simple static-site generator based on Markdown. +The main goal of Crocc is to offer simplicity, as opposed to other static-site +generation tools such as Hugo or Jekyll. +Indeed, you only need Markdown to write content in a productive manner, and +everything else is standard scripts (JavaScript, CSS, images, etc.). + +![A crocodile walking](/assets/crocodile.jpg) + +## Installation + +To install Crocc from sources, you need to have Go installed on your system. +Then, run the following command: + +```bash +$ go install go.nc0.fr/crocc@latest +``` + +> Note: You can replace `latest` with a specific Git commit. + +## Usage + +Let's say you have a directory containing the following files: + +``` +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! + +## Documentation + +See the [documentation](/doc) for more information. + +## License + +The project is governed by a BSD-style license that can be found in the +[LICENSE](https://github.com/n1c00o/crocc/blob/master/LICENSE) file. + +The banner image is a [photo](https://unsplash.com/photos/R3sgrDvXz3I) from +[Unsplash](https://unsplash.com/) by +[Thomas Couillard](https://unsplash.com/@thomascouillard). + +Favicons are Noto emojis and are licensed under the +[Apache License 2.0](https://github.com/googlefonts/noto-emoji/blob/main/LICENSE) +license. diff --git a/doc/src/robots.txt b/doc/src/robots.txt new file mode 100644 index 0000000..c699321 --- /dev/null +++ b/doc/src/robots.txt @@ -0,0 +1,4 @@ +User-Agent: * +Allow: / + +Sitemap: https://crocc.nc0.fr/sitemap.xml diff --git a/doc/src/sitemap.xml b/doc/src/sitemap.xml new file mode 100644 index 0000000..b9557a6 --- /dev/null +++ b/doc/src/sitemap.xml @@ -0,0 +1,23 @@ + + + + + https://crocc.nc0.fr/ + + + https://crocc.nc0.fr/doc + + + https://crocc.nc0.fr/doc/iodir + + + https://crocc.nc0.fr/doc/markdown + + + https://crocc.nc0.fr/doc/template + + \ No newline at end of file diff --git a/doc/src/style.css b/doc/src/style.css new file mode 100644 index 0000000..b8dfd9f --- /dev/null +++ b/doc/src/style.css @@ -0,0 +1,91 @@ +/** + * 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. + */ + +/* TODO: Replace it with future common CSS */ + +:root { + --background-color: #FFFFFF; + --text-color: #000000; + --accent-color: #155eca; +} + +/* Auto Dark Theme */ +@media (prefers-color-scheme: dark) { + :root { + --background-color: #000000; + --text-color: #FFFFFF; + --accent-color: #648fd0; + } +} + +html { + background-color: var(--background-color); + color: var(--text-color); + font-family: sans-serif; + margin: 0.6rem; +} + +main { + padding-top: 1rem; + padding-bottom: 3rem; +} + +h1, +h2, +h3, +h4, +h5, +h6, +p, +blockquote { + max-width: 80ch; + line-height: 150%; +} + +code, +kbd, +samp, +pre { + font-family: monospace; +} + +a { + color: var(--accent-color); +} + +img { + width: 100%; + height: auto; +} + +strong { + font-weight: bold; +} + +em { + font-style: italic; +} + +hr { + border: 0; + border-top: 1px solid var(--accent-color); +} + +td { + max-width: 80ch; + padding: 0 15px; +} + +/* Navigation Bar and Footer */ +header ul, +footer ul { + list-style-type: none; + display: inline-flex; + gap: 1rem; + flex-wrap: wrap; + align-items: center; + padding-left: 0; +} \ No newline at end of file -- cgit v1.2.3