add documentation

site/pages/docs/commands.md

@@ -0,0 +1,102 @@
+---
+title: commands
+template: docs.tera
+---
+
+# webdog commands
+
+global options:
+
+```
+--site <SITE_PATH>  The path to the site [default: .]
+-h, --help          Print help
+```
+
+## `webdog create`
+
+```
+Create a new webdog site
+
+Usage: webdog create [OPTIONS] <BASE_URL> <TITLE>
+
+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
+```

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.

site/pages/docs/extras.md

@@ -0,0 +1,10 @@
+---
+title: extras
+template: null
+embed: null
+scripts: []
+styles: []
+extra: null
+---
+
+new page :)

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

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.

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.

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.

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 }}</title>
+</head>
+```
+
+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 `<head>` html element like so:
+
+```html
+<head>
+  {{ head | safe }}
+</head>
+```
+
+this variable will be removed before the first crates.io release.
+
+### `scripts`
+
+the page's extra scripts. this should be rendered in the `<head>` html element like so:
+
+```html
+<head>
+  {% for script in scripts %}
+  <script type="text/javascript" src="{{script}}" defer></script>
+  {% endfor %}
+</head>
+```
+
+this variable will be removed before the first crates.io release.
+
+### `styles`
+
+the page's extra stylesheets. this should be rendered in the `<head>` html element like so:
+
+```html
+<head>
+  {% for style in styles %}
+  <link rel="stylesheet" href="/styles/{{style}}" />
+  {% endfor %}
+</head>
+```
+
+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
+<main class="page">
+  {% block content %}{{ page | safe }}{% endblock content %}
+</main>
+```

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

site/templates/base.tera

@@ -21,13 +21,16 @@
 			<a class="name" href="/">webdog</a>
 		</span>
 		<span class="spacer"></span>
+		<a href="/docs/">documentation</a> |
 		<a href="/blog/">blog</a> |
 		<a href="https://github.com/zyllian/webdog" rel="noopener noreferrer">github</a>
 	</header>
 	<div id="content">
+		{% block precontent %}{% endblock precontent %}
 		<main class="page">
 			{% block content %}{{ page | safe }}{% endblock content %}
 		</main>
+		{% block postcontent %}{% endblock postcontent %}
 	</div>
 </body>
 

site/templates/docs.tera

@@ -0,0 +1,20 @@
+{% extends "base.tera" %}
+
+{% macro docLink(text, href, first=false) %}
+{% if not first %}• {% endif %}
+<a href="/docs/{{href}}">{{ text }}</a>
+{% endmacro docLink %}
+
+{% block content %}
+<div class="docs-links">
+	{{ 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") }}
+</div>
+{{ page | safe }}
+{% endblock precontent %}