diff --git a/site/pages/docs/commands.md b/site/pages/docs/commands.md new file mode 100644 index 0000000..f0d0d8f --- /dev/null +++ b/site/pages/docs/commands.md @@ -0,0 +1,102 @@ +--- +title: commands +template: docs.tera +--- + +# webdog commands + +global options: + +``` +--site The path to the site [default: .] +-h, --help Print help +``` + +## `webdog create` + +``` +Create a new webdog site + +Usage: webdog create [OPTIONS] + +Arguments: + <BASE_URL> The site's base URL + <TITLE> The site's title + +Options: + --cdn-url <CDN_URL> The site's CDN URL. (defaults to the base URL) +``` + +## `webdog build` + +``` +Builds the site + +Usage: webdog build [OPTIONS] +``` + +## `webdog serve` + +``` +Serves the site for locally viewing edits made before publishing + +Usage: webdog serve [OPTIONS] + +Options: + --ip <IP> The IP address to bind to [default: 127.0.0.1] + -p, --port <PORT> The port to bind to [default: 8080] +``` + +## `webdog now` + +``` +Helper to get the current timestamp + +Usage: webdog now [OPTIONS] +``` + +## `webdog resource create` + +``` +Creates a new resource type + +Usage: webdog resource create [OPTIONS] <ID> <NAME> <PLURAL> + +Arguments: + <ID> The resource type's ID + <NAME> The name of the resource type to create + <PLURAL> The name of the resource type, but plural +``` + +## `webdog page new` + +``` +Creates a new standard page + +Usage: webdog page new [OPTIONS] <ID> [TITLE] + +Arguments: + <ID> The page's ID + [TITLE] The page's title + +Options: + --template <TEMPLATE> The page's base template if using one other than the default +``` + +## `webdog new` + +``` +Creates a new resource of the given type + +Usage: webdog new [OPTIONS] <RESOURCE_TYPE> <ID> <TITLE> + +Arguments: + <RESOURCE_TYPE> The type of resource to create + <ID> The resource's ID + <TITLE> The resource's title + +Options: + -t, --tag <TAGS> The resource's tags + -d, --description <DESCRIPTION> The resource's description + --skip-draft Whether to skip setting the resource as a draft or not +``` diff --git a/site/pages/docs/config.md b/site/pages/docs/config.md new file mode 100644 index 0000000..a9a9e41 --- /dev/null +++ b/site/pages/docs/config.md @@ -0,0 +1,42 @@ +--- +title: config +template: docs.tera +--- + +# webdog configuration + +your webdog site must have a `config.yaml` file in its root with the following keys: + +## `base_url` + +simply the site's base url. + +## `title` + +the site's base title applied to all pages. + +## `description` + +presently unused field, set this to any string you like. + +## `build` + +the directory for the site to build to. defaults to `<site-path>/build` if not specified. + +**!!WARNING!! this may not function properly, it is untested in any version and should not be relied upon in future versions** + +## `sass_styles` + +list of sass/scss stylesheets in the site's `sass` directory to treat as root stylesheets and build. + +## `cdn_url` + +base url for the various cdn url transformation features of webdog. + +## `code_theme` + +the theme to use for code blocks. valid options: `base16-ocean.dark`, `base16-eighties.dark`, `base16-mocha.dark`, `base16-ocean.light`, `InspiredGitHub`, `Solarized (dark)`, and `Solarized (light)` + +## `resources` + +configuration information for your site's resource types. must be present, even if no resources have been added. see <a href="resources">resources documentation</a> for more info. diff --git a/site/pages/docs/extras.md b/site/pages/docs/extras.md new file mode 100644 index 0000000..4f0a15e --- /dev/null +++ b/site/pages/docs/extras.md @@ -0,0 +1,10 @@ +--- +title: extras +template: null +embed: null +scripts: [] +styles: [] +extra: null +--- + +new page :) diff --git a/site/pages/docs/index.md b/site/pages/docs/index.md new file mode 100644 index 0000000..67aba69 --- /dev/null +++ b/site/pages/docs/index.md @@ -0,0 +1,33 @@ +--- +title: documentation +--- + +# webdog documentation + +## <a href="commands">commands</a> + +get an overview of the various commands available in the `webdog` cli tool here + +## <a href="config">configuration</a> + +learn how to configure your webdog site + +## <a href="pages">pages</a> + +learn about standard webdog pages here + +## <a href="templates">templates</a> + +learn how to use webdog templates + +## <a href="styling">styling</a> + +learn about webdog styling + +## <a href="resources">resources</a> + +learn how to utilize the webdog resource feature in your site + +## <a href="wd-assumptions">webdog assumptions</a> + +learn about the assumptions webdog makes about your site and how not to break them diff --git a/site/pages/docs/pages.md b/site/pages/docs/pages.md new file mode 100644 index 0000000..3a6593f --- /dev/null +++ b/site/pages/docs/pages.md @@ -0,0 +1,100 @@ +--- +title: pages +template: docs.tera +--- + +# pages + +webdog pages essentially just markdown files with extra features. + +to add a new page to your site, just run this command: + +```sh +webdog page new <id> <title> +``` + +you may safely create standard pages in subdirectories by using slashes in your id. + +## yaml front matter + +all standard webdog pages _may_ include yaml front matter. example: + +```md +--- +title: page title +--- + +# page header :) +``` + +yaml front matter may contain the following options: + +### `title` + +the page's title to be displayed next to the base title, i.e. `webdog / pages` for this page. + +### `template` + +the template to use for the page. if not specified, defaults to `base.tera`. + +### `embed` + +custom embed information for the page, useful for linking on social media. + +table containing the following fields: + +#### `title` + +the custom embed's title. + +#### `site_name` + +the site name to use for the embed. + +#### `description` + +the embed's description. optional. + +#### `url` + +full url for the embed. optional? + +#### `image` + +full url to an image to use for the embed. optional. + +#### `theme_color` + +the theme color to use for the embed. optional, but the default is currently nonconfigurable. + +#### `large_image` + +used by some sites to determine the size of the image when displayed. `true` or `false`. + +### `scripts` + +list of extra scripts to include in the page. + +### `styles` + +list of extra stylesheets to include in the page. + +### `extra` + +see <a href="extras">extras documentation</a> for more info on this field. + +## special features + +in addition to standard markdown, webdog comes with some minor additions for ease of use. + +### links + +links may have commands embedded into them. example: + +```md +[example](command$url) +``` + +currently, the only command is `me`, which adds a `rel="me"` value to the link, useful for certain social media platforms' link verification features. + +additionally, any external links will be given `target="_blank"` and `rel="noopener noreferrer"` fields to open in a new tab automatically. this is currently nonconfigurable. diff --git a/site/pages/docs/resources.md b/site/pages/docs/resources.md new file mode 100644 index 0000000..1efc5f0 --- /dev/null +++ b/site/pages/docs/resources.md @@ -0,0 +1,150 @@ +--- +title: resources +template: docs.tera +--- + +# resources + +resources are a highly configurable aspect of webdog used for taggable things which generally follow a similar layout across entries. for instance, a blog or photo album. + +for instructions on how to add a resource via the cli, see the [commands page](./commands). + +## resource config + +each resource added has its own configuration inside of the main site config file with the following properties: + +### `source_path` + +the source path for where the resources of this type are located, relative to `<site_path>/resources/`. + +### `output_path_short` + +the path prefix for a resource, i.e. "blog" for `/blog/<post id>` or "i" for `/i/<image id>`. can be shared with `output_path_long` for them to have the same prefix. + +### `output_path_long` + +the path prefix for other resource pages, like the overview or tags. i.e. "blog" for `/blog/tags/<tag>` or "images" for `/images/tags/<tag>`. can be shared with `output_path_short` for them to have the same prefix. + +### `resource_template` + +the template to use for the main page of a resource item. + +this template is provided the resource's properties (defined below) as variables. this should change to be `r.<property>` before the first crates.io release to avoid conflicts with page properties. + +### `resource_list_template` + +the template to use for a list of resources. + +this template is provided with the following properties: + +#### `previous` + +if this property exists, it can be used as `./{{previous}}` to get a link to the previous list page. + +#### `next` + +if this property exists, it can be used as `./{{next}}` to get a link to the next list page. + +#### `resources` + +a array of the resources to be rendered on this page. each resource in the array contains the resource properties as defined below. + +### `tag_list_template` + +the template to use for a list of tags assigned to the resource. + +this template is provided with the following properties: + +#### `title` + +the title of the tag list. + +this property will be renamed before the crates.io release to fix its conflict with page titles. + +#### `links` + +array of the links available for this list, containing the following properties: + +##### `link` + +the link to actually use for the link. + +##### `title` + +the link's title. + +### `rss_template` + +the template used to render the resource type's rss feed's html content. + +this template is provided a single resource's properties as its properties. + +### `rss_title` + +the title for the resource type's rss feed. + +### `rss_description` + +the description for the resource type's rss feed. + +### `list_title` + +the title to use for a list of resources of this type. + +### `tag_list_title` + +the title to use for a list of tags for this resource t ype. + +### `resource_name_plural` + +the name of this resource type if it is plural. + +### `resources_per_page` + +how many resources of this type to display per page when content is paginated. + +## defining a resource + +resources are made up of markdown files with yaml front matter. for instance: + +```md +--- +title: resource title +timestamp: 2024-11-13T00:55:46.888967374Z +tags: [first tag, second tag] +--- + +# hiiiiiii :3 +``` + +the front matter metadata may contain the following properties: + +### `title` + +the resource's title, as displayed in the browser tab. + +### `timestamp` + +the timestamp to use as the resource's publishing time. probably shouldn't be altered after publishing publicly, but it won't break anything. + +the timestamp follows the [RFC 3339 format](https://www.rfc-editor.org/rfc/rfc3339). use the `webdog now` command to get a timestamp of the proper format easily. + +### `tags` + +array of the resource's tags. tags are used to group resources together and are at present **required**. + +### `cdn_file` (optional) + +special property which will take a relative url and add the cdn prefix as defined in the site config to it. + +### `desc` (optional) + +property for a resource's short description. + +### `draft` (optional) + +whether the resource is a draft and should be excluded from normal builds. defaults to false. + +### other properties + +resources may add extra properties which will get passed to the various resource templates later. simply add the property like it was any other property. diff --git a/site/pages/docs/styling.md b/site/pages/docs/styling.md new file mode 100644 index 0000000..2d3fc36 --- /dev/null +++ b/site/pages/docs/styling.md @@ -0,0 +1,10 @@ +--- +title: styling +template: docs.tera +--- + +# styling + +though you can use plain CSS if you prefer, webdog includes [Sass](https://sass-lang.com) support out-of-the-box and is recommended. + +add your root Sass stylesheets to your [site config](./config), but replace the extension with `.css` when adding the `link` tag to your templates. diff --git a/site/pages/docs/templates.md b/site/pages/docs/templates.md new file mode 100644 index 0000000..c947489 --- /dev/null +++ b/site/pages/docs/templates.md @@ -0,0 +1,104 @@ +--- +title: templates +template: docs.tera +--- + +# webdog templates + +in webdog, [Tera](https://keats.github.io/tera/) templates are used as the backbone for your site. as used in webdog, your Tera templates are essentially just an extension on top of html. + +when you create your site, a file at `templates/base.tera` will be created, acting as the default base template for all pages. + +## base template variables + +a great deal of information is given to templates used as bases, such as: + +### `title` + +the page's title. used to set the page's title in the head, though this will no longer be needed in a future update. + +### `head` + +html code which must be written to the head using the safe filter. will be removed in a future update. + +### `scripts` + +a list of extra scripts to apply to the page. will be removed in a future update. + +### `styles` + +a list of extra stylesheets to apply to the page. will be removed in a future update. + +### `page` + +html code for the page. must be rendered to the page using the safe filter. + +## base template blocks + +all base templates should include a block named `content`. this will be used in other templates, particularly resource templates, to render to the correct location on the page. + +## template data + +all templates are given the following variables: + +### `title` + +the page's title. this should be rendered in the `<head>` html element like so: + +```html +<head> + <title>{{ title }} + +``` + +this variable will no longer be required to set the page title before the first crates.io release. + +### `head` + +the page's extra head data. this should be rendered in the `` html element like so: + +```html + + {{ head | safe }} + +``` + +this variable will be removed before the first crates.io release. + +### `scripts` + +the page's extra scripts. this should be rendered in the `` html element like so: + +```html + + {% for script in scripts %} + + {% endfor %} + +``` + +this variable will be removed before the first crates.io release. + +### `styles` + +the page's extra stylesheets. this should be rendered in the `` html element like so: + +```html + + {% for style in styles %} + + {% endfor %} + +``` + +this variable will be removed before the first crates.io release. + +### `page` + +the main html content for the page to be rendered. can be rendered anywhere you choose, for instance: + +```html +
+ {% block content %}{{ page | safe }}{% endblock content %} +
+``` diff --git a/site/pages/docs/wd-assumptions.md b/site/pages/docs/wd-assumptions.md new file mode 100644 index 0000000..695038f --- /dev/null +++ b/site/pages/docs/wd-assumptions.md @@ -0,0 +1,14 @@ +--- +title: webdog assumptions +template: docs.tera +--- + +# webdog assumptions + +although webdog can be used to make many different kinds of static website, there are some assumptions it makes about your site's layout which must be followed. + +- there must be a template named "base.tera". pages without a template will assume this is their base template. + +- there must be a page named "404.md". this page will be used if a page can't be found. + +- other things i'm sure i'm forgetting diff --git a/site/templates/base.tera b/site/templates/base.tera index 85c76b7..6c7152b 100644 --- a/site/templates/base.tera +++ b/site/templates/base.tera @@ -21,13 +21,16 @@ webdog + documentation | blog | github
+ {% block precontent %}{% endblock precontent %}
{% block content %}{{ page | safe }}{% endblock content %}
+ {% block postcontent %}{% endblock postcontent %}
diff --git a/site/templates/docs.tera b/site/templates/docs.tera new file mode 100644 index 0000000..d606195 --- /dev/null +++ b/site/templates/docs.tera @@ -0,0 +1,20 @@ +{% extends "base.tera" %} + +{% macro docLink(text, href, first=false) %} +{% if not first %}• {% endif %} +{{ text }} +{% endmacro docLink %} + +{% block content %} +
+ {{ self::docLink(text="docs", href="", first=true) }} + {{ self::docLink(text="commands", href="commands") }} + {{ self::docLink(text="configuration", href="config") }} + {{ self::docLink(text="pages", href="pages") }} + {{ self::docLink(text="templates", href="templates") }} + {{ self::docLink(text="styling", href="styling") }} + {{ self::docLink(text="resources", href="resources") }} + {{ self::docLink(text="webdog assumptions", href="wd-assumptions") }} +
+{{ page | safe }} +{% endblock precontent %}