Documentation

cdp1337 · Oct 27, 2023 · 29c49f6 · 29c49f6
1 parent d4259fa
commit 29c49f6
Show file tree

Hide file tree

Showing 17 changed files with 278 additions and 202 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,4 @@
-## 4.NEXT - 2023-XX-XX
+## 4.1.0 - 2023-XX-XX
 
 ### New Features
 
@@ -11,10 +11,12 @@
 * Fix cms-* plugins trying to run before CMS was initialized
 * Switch example site to use minified version of app by default
 * Include default config for Apache expiry headers (for caching)
+* Fix paragraph stealing extended attributes for simple blocks
 
 ### Changes
 
 * Mastodon Share is now an element as opposed to a plugin
+* Switch to `is=...` for all custom elements
 
 
 ## 4.0.2 - 2023-10-23

diff --git a/README.md b/README.md
@@ -15,9 +15,12 @@ the auto-index feature in either
 or [Nginx](https://nginx.org/en/docs/http/ngx_http_autoindex_module.html) and performs 
 all processing of templates and content within the browser.
 
-Note* there _is_ a server-side component written as a Python CGI script to 
-better facilitate crawlers, bots, and search engines.  This component utilizes the 
-same flat files and templates as the client-side application.
+Note* for SEO reasons, there is a server-side Python component
+which will return a generated version of the requested page similar to the
+client-side application.  This is unnecessary for normal users, but is required
+to ensure that crawlers can access the site data.
+
+This feature can be disabled via `.htaccess` or `nginx.conf` if desired.
 
 Because there is no database, registry, or administration of pages, 
 deploying new pages is as simple as just uploading Markdown files to your server.
@@ -45,8 +48,10 @@ This project is originally based from
 * Search, filtering, tagging and sorting
 * Apache, Nginx, Mail-in-a-box, and Nextcloud support
 * Small footprint
-* [marked.js](https://github.com/markedjs/marked) embedded
-* Automatic body classes based on page
+* [marked.js](https://github.com/markedjs/marked) embedded (still included, but not 
+  used by default)
+* [Remarkable](https://github.com/jonschlinkert/remarkable) embedded
+* Automatic body classes based on page (addon)
 * Native JS events
 * Full [History API](https://developer.mozilla.org/en-US/docs/Web/API/History) support
 * Crawler and SEO support for most content
@@ -62,7 +67,9 @@ Check out a [live working site](https://veraciousnetwork.com)!
 
 1. Download the [latest release](https://github.com/cdp1337/markdownmaster/releases/latest)
 2. Setup environment, refer to specific documentation for 
-   [NextCloud](docs/INSTALL.nextcloud-nginx.md) or [Mail-in-a-Box](docs/INSTALL.mailinabox.md)
+   [NextCloud](docs/INSTALL.nextcloud-nginx.md),
+   [Mail-in-a-Box](docs/INSTALL.mailinabox.md),
+   or [Apache](docs/INSTALL.apache.md) for more information.
 3. [Configure config.js and config.ini](docs/site-configuration.md) to your liking
 
 
@@ -76,8 +83,9 @@ take a look through the other [post examples](examples/posts/) and the various
 * [Using plugins](docs/plugins-overview.md)
 * [Hooking into native events](docs/document-events.md)
 * [Authoring content](docs/authoring-pages.md)
-* [Content Sorting](docs/sorting.md)
-* [Development Guide](docs/development.md)
+* [Extended attributes](docs/markdown-extended-attributes.md)
+* [Content sorting](docs/sorting.md)
+* [Development guide & build instructions](docs/development.md)
 
 
 ## How it works

diff --git a/RELEASE.md b/RELEASE.md
@@ -3,155 +3,26 @@
 
 ## New Features
 
-* Include a simple background-slider plugin
-* Include fslightbox-basic for a simple lightbox
+* Add 'random' as supported sort parameter
+* Paginate now supports 'page' parameter
+* Page-list now supports 'limit' parameter
 
 ## Fixes
 
-* Fix support for Apache web servers
-
+* Fix cms-* plugins trying to run before CMS was initialized
+* Switch example site to use minified version of app by default
+* Include default config for Apache expiry headers (for caching)
+* Fix paragraph stealing extended attributes for simple blocks
 
 ## Changes
 
+* Mastodon Share is now an element as opposed to a plugin
+* Switch to `is=...` for all custom elements
 
 
+## Upgrade Notes
 
-## Upgrade from 2.x
-
-Since this has been a substantial rewrite, some features will require updating, 
-(depending on what is used on your specific site).
-
-### URLs
-
-Page URLs have been changed from query hashes to full standard URLs via the History API. 
-This requires a new `.htaccess` or `nginx.conf` to be installed 
-(depending on the server you chose).  Consult the respective file within `examples/`.
-
-### Plugins
-
-Plugins have been retooled and need refactored to work correctly. 
-Given the default example plugin:
-
-```js
-// 2.x Example plugin
-function myPlugin() {
-	// Do some code
-	console.log('loading test plugin');
-}
-
-// Config
-var config = {
-
-  // ...
-
-  // Pass in any custom functions or plugins here and access the CMS object.
-  plugins: [
-  	myPlugin,
-  ],
-
-  // ...
-
-  // This function will be called once the CMS instance is loaded and ready.
-  onload: function() {
-
-    // ...
-
-    // Access the loaded plugins like this.
-    blog.myPlugin();
-  },
-};
-```
-
-This example plugin would need to be rewritten to:
-
-```js
-// 3.x+ plugin
-blog.registerPlugin(
-  'myPlugin', 
-  {
-    init: () => {
-      // Do some code
-      console.log('loading test plugin');
-    }
-  }
-);
-
-// Access the loaded plugins like this.
-blog.getPlugin('myPlugin');
-```
-
-### onload/onroute
-
-The configurable options `onload` and `onroute` are still supported, 
-but this functionality has been ported to the following code:
-
-```js
-/**
- * Called immediately upon successful initialization of the CMS
- * 
- * @param {CMS} event.detail.cms The CMS object passed for reference
- */
-document.addEventListener('cms:load', event => {
-  event.detail.cms.debuglog('CMS initialized and ready to run user-specific code!', event.detail.cms);
-});
-
-/**
- * Called after any page load operation
- * 
- * @param {CMS} event.detail.cms CMS object for reference if needed
- * @param {FileCollection[]|null} event.detail.collection Collection of files to view for listing pages
- * @param {File|null} event.detail.file Single file to view when available
- * @param {string} event.detail.mode Type of view, usually either "list", "single", or error.
- * @param {string} event.detail.search Any search query
- * @param {string} event.detail.tag Any tag selected to view
- * @param {string} event.detail.type Content type selected
- */
-document.addEventListener('cms:route', event => {
-  event.detail.cms.debuglog('Page being displayed', event.detail);
-});
-```
-
-
-## Upgrade from 3.0.x
-
-1. Configure `cgi-bin/config.ini` with values that mimic `js/config.js`
-2. Upload `cgi-bin` to your server
-3. Add new directives from `nginx.conf` into your site config
-4. Run the following code (with the appropriate SITEPATH)
-
-```bash
-apt install fcgiwrap python3 python3-venv
-python3 -m venv /opt/markdownmaster
-/opt/markdownmaster/bin/pip3 install Markdown beautifulsoup4 python-frontmatter lxml
-chmod +x "${SITEPATH}/cgi-bin/crawler.py"
-chmod +x "${SITEPATH}/cgi-bin/sitemap.py"
-chmod +x "${SITEPATH}/cgi-bin/meta.py"
-```
-
-
-## Upgrade from 3.1.x
-
----
-
-Tags and other lists in Markdown files now expect to be YAML-compatible lists
-
-* `tags: blah, foo` => `tags: [blah, foo]`
-* Dates listed as `date: 2023-01-01` will be rendered as Date objects,
-switch to `date: '2023-01-01'` (with quotes) for best results
-
----
-
-Banners and images no longer auto-resolve as URLs, instead `src` or `href` needs to be
-used in YAML data
-
-* `banner: somefile.jpg` => `banner: { src: somefile.jpg }`
-
----
-
-Moved some plugins to built-in
-
-* `site.enablePlugin(['pagelist'])` => N/A (built-in)
-* `site.enablePlugin(['search'])` => N/A (built-in)
-* `site.enablePlugin(['remarkable'])` NEW RENDERER
-
----
+* [From 2.x](docs/upgrade-notes/upgrade-2.x-to-3.0.md)
+* [From 3.0](docs/upgrade-notes/upgrade-3.0-to-3.1.md)
+* [From 3.1](docs/upgrade-notes/upgrade-3.1-to-4.0.md)
+* [From 4.0](docs/upgrade-notes/upgrade-4.0-to-4.1.md)
diff --git a/docs/INSTALL.apache.md b/docs/INSTALL.apache.md
@@ -1,6 +1,8 @@
 Apache2 can be used to host your own site, but needs a module to be enabled for best results.
 
-`rewrite` is required as it will allow URLs to be rewritten and resolved via the History API.  This will also perform rewrites for search crawlers to ensure they retrieve content when crawling the various .html links.
+`rewrite` is required as it will allow URLs to be rewritten and resolved via the History API. 
+This will also perform rewrites for search crawlers to ensure they retrieve content 
+when crawling the various .html links.
 
 
 ## Setup apache (tested on Debian/Ubuntu)
@@ -11,17 +13,21 @@ Enable the modules necessary and restart the web server.
 
 ## Install Files
 
-Extract the application, (including hidden `.htaccess` files) to `/var/www/html` (or other directory should you choose).
+Extract the application, (including hidden `.htaccess` files) to `/var/www/html`,
+`public_html`, or whatever directory your website resides.
 
 ## Configure Environment
 
-If your web application is installed in a directory OTHER than the default top-level path, edit `.htaccess` and set the `RewriteBase` directive as necessary.  For example if your site is installed in `/var/www/html/mycms` and is retrieved via `https://domain.tld/mycms`, your `.htaccess` should resemble the following:
+If your web application is installed in a directory OTHER than the default top-level path, 
+edit `.htaccess` and set the `RewriteBase` directive as necessary. 
+For example if your site is installed in `/var/www/html/mycms` 
+and is retrieved via `https://domain.tld/mycms`, your `.htaccess` should resemble the following:
 
 ```.htaccess
   # Set this line to the value of config.webpath
-	RewriteBase /mycms/
+  RewriteBase /mycms/
 ```
 
 ## Configure Application
 
-Follow standard steps for configuring the application via `js/config.js`.
+Follow standard steps for configuring the application via `js/config.js` and `cgi-bin/config.ini`.
diff --git a/docs/authoring-pages.md b/docs/authoring-pages.md
@@ -105,6 +105,23 @@ call_to_action:
 | tags      | Comma-separated list of tags for the content on this page             |
 | image     | Fully resolve or relative path to preview image of this page          |
 
+### Protected Attributes
+
+DO NOT USE THESE! 
+These are reserved for internal use only, but are available for use in your templates.
+
+| Attribute   | Description                                                           |
+|-------------|-----------------------------------------------------------------------|
+| body        | The raw markdown content of this page                                 |
+| bodyLoaded  | The rendered HTML content of this page                                |
+| config      | The configuration object for this page                                |
+| content     | The rendered HTML content of this page                                |
+| name        | The filename of this page                                             |
+| permalink   | The permalink of this page                                            |
+| type        | The type of content this is (page, post, etc)                         |
+| url         | The URL of this page                                                  |
+
+
 Other attributes can be used, but will need to be added within your layout templates to make use of them.
 
 
@@ -149,38 +166,3 @@ relative to that file.  Top-level paths (starting with `/`) and absolute request
 (`https://...`) paths are also supported.
 
 
-## Extended Markdown Functionality
-
-All base markdown features will work, and a number of extended features have 
-been added to better support web publishing.
-
-### HTML Attributes
-
-HTML attributes can be set on some elements, including:
-
-* paragraphs
-* links
-* images
-
-To use HTML attributes, append `{...}` to the end of the line with the HTML tags inside.
-As some examples:
-
-Short paragraph with `class="center"` added
-
-```markdown
-This is a short example paragraph {.center}
-```
-
-This link will have a `title` and `target` set
-
-```md
-[Go Search](https://www.duckduckgo.com) {title="Search for something" target=_blank}
-```
-
-This image will have a border
-
-```markdown
-![test image](test.png) {style="border:5px solid pink;"}
-```
-
-Any valid HTML tag can be used and CSS shorthand for class (`.` prefix) and ID (`#` prefix) are also supported.
diff --git a/docs/cms-author.md b/docs/cms-author.md
@@ -24,6 +24,8 @@ The template to use for rendering the author content
 
 ```html
 <% if(data.author) { %>
-    <cms-author author="<%= data.author %>" layout="author-embed"><%= data.author %></cms-author>
+    <div is="cms-author" author="<%= data.author %>" layout="author-embed">
+        <%= data.author %>
+    </div>
 <% } %>
 ```
diff --git a/docs/cms-button.md b/docs/cms-button.md
@@ -35,5 +35,5 @@ Renders to
 Also usable from within Markdown pages
 
 ```markdown
-[Download this Thing](https://site.tld) {is=cms-button icon=download}
+[Download this Thing](https://site.tld){is=cms-button icon=download}
 ```
diff --git a/docs/cms-icon.md b/docs/cms-icon.md
@@ -15,5 +15,5 @@ If a "brand" icon is used, the brand library will be loaded.
 **Example**
 
 ```.html
-<cms-icon icon="gitlab"/>
+<i is="cms-icon" icon="gitlab"/>
 ```
diff --git a/docs/cms-mastodon-share.md b/docs/cms-mastodon-share.md
@@ -11,8 +11,8 @@ At the moment no parameters are configurable
 **Example**
 
 ```.html
-<cms-mastodon-share href="#" class="mastodon-share-button">
-  <cms-icon icon="mastodon"/>
+<a is="cms-mastodon-share" href="#">
+  <i is="cms-icon" icon="mastodon"/>
   Share on Mastodon
-</cms-mastodon-share>
+</a>
 ```
diff --git a/docs/cms-pagelist.md b/docs/cms-pagelist.md
@@ -18,7 +18,14 @@ Render a list of pages which match given parameters.
 **Example**
 
 ```.html
-<cms-pagelist type="pages" layout="page-list" link="pages/games/" sort="title" limit="5">
+<div 
+    is="cms-pagelist" 
+    type="pages" 
+    layout="page-list" 
+    link="pages/games/" 
+    sort="title" 
+    limit="5"
+>
   Loading Content...
-</cms-pagelist>
+</div>
 ```