diff --git a/assets/scss/common/_variables.scss b/assets/scss/common/_variables.scss index e22f473..6a01652 100644 --- a/assets/scss/common/_variables.scss +++ b/assets/scss/common/_variables.scss @@ -162,3 +162,5 @@ $alert-border-width: 0; $alert-bg-scale: 0; $alert-border-scale: 0; $alert-color-scale: 0; + +$code-bg: #24292e; \ No newline at end of file diff --git a/assets/scss/components/_code.scss b/assets/scss/components/_code.scss index 7f98867..778cc3f 100644 --- a/assets/scss/components/_code.scss +++ b/assets/scss/components/_code.scss @@ -27,10 +27,6 @@ pre code { scrollbar-color: transparent transparent; } -.hljs { - padding: 1.25rem 1.5rem; -} - @include media-breakpoint-down(sm) { pre, code, diff --git a/assets/scss/components/_syntax.scss b/assets/scss/components/_syntax.scss index d132cb5..ffb063f 100644 --- a/assets/scss/components/_syntax.scss +++ b/assets/scss/components/_syntax.scss @@ -7,9 +7,13 @@ Based on Ascetic by (c) Ivan Sagalaev .hljs { display: block; overflow-x: auto; - padding: 1.25rem 1.5rem; - background: $body-overlay-dark; + padding: 1.25rem 1.5rem !important; + background: $body-bg-dark !important; color: $body-color-dark; + + .dark & { + background: $body-overlay-dark !important; + } } .hljs-string, @@ -60,3 +64,7 @@ body.dark .hljs-attribute, body.dark .hljs-link { color: $blue-300; } + +code { + background: $gray-100; +} diff --git a/assets/scss/layouts/_docs.scss b/assets/scss/layouts/_docs.scss index fb6e572..c576db6 100644 --- a/assets/scss/layouts/_docs.scss +++ b/assets/scss/layouts/_docs.scss @@ -20,7 +20,7 @@ nav.docs-links { code.language-bash { overflow-x: scroll; - white-space: nowrap; + white-space: pre; line-height: 2; } diff --git a/config/_default/config.toml b/config/_default/config.toml index 56fc5c8..498b93d 100644 --- a/config/_default/config.toml +++ b/config/_default/config.toml @@ -96,3 +96,6 @@ rel = "sitemap" [[module.mounts]] source = "node_modules/mermaid" target = "assets/js/vendor/mermaid" + [[module.mounts]] + source = "node_modules/@highlightjs/cdn-assets" + target = "static/assets/js/vendor/hljs" diff --git a/config/_default/menus.toml b/config/_default/menus.toml index e0e003f..e426468 100644 --- a/config/_default/menus.toml +++ b/config/_default/menus.toml @@ -19,13 +19,21 @@ identifier = "configuration" url = "/docs/configuration/" +[[docs]] + name = "Templating" + pre = "bi-braces-asterisk" + weight = 30 + identifier = "templating" + url = "/docs/templating/" + [[docs]] name = "Reference" pre = "bi-circle-square" - weight = 30 + weight = 40 identifier = "reference" url = "/docs/reference/" + [[docs]] name = "Help" pre = "bi-question-circle-fill" diff --git a/content/docs/configuration/actions.md b/content/docs/configuration/actions.md new file mode 100644 index 0000000..191edf1 --- /dev/null +++ b/content/docs/configuration/actions.md @@ -0,0 +1,74 @@ +--- +title: "actions" +member: true +lastmod: 2020-10-13T15:21:01+02:00 +draft: false +images: [] +menu: + docs: + parent: "configuration" +weight: 100 +toc: true +--- + +The `"actions"` configuration option is a convenient way to register [WordPress hooks](https://developer.wordpress.org/apis/hooks/action-reference/). Simply pass the hook name, an optional priority value, and a function to call when the hook is triggered. + +## Usage + +| Key | Type | Required | Default | +| ----------- | ------- | -------- | ------- | +| `"actions"` | `array` | No | `[]` | + +Where `"actions"` is an array of objects that follow this structure: + +## Action Object + +```php +// The Action Object + +[ + "hook" => "wp_loaded", + "priority" => 50, + "callback" => function() { ... } +] + +// Evaluates to: +add_action("wp_loaded", function() { ... }, 50); +``` + +| Key | Type | Required | Description | +| ------------ | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | +| `"hook"` | `string` | Yes | The name of the [WordPress hook](https://developer.wordpress.org/apis/hooks/action-reference/) to register upon. | +| `"callback"` | `function` | Yes | The callback function to trigger when this hook is called. | +| `"priority"` | `integer` | No | An optional priority value. Defaults to `99`, meaning it will likely run after any other functions registered to this hook. | + +## Example + +
config.php
+ +```php +return [ + "actions" => [ + + // Register an action to be performed after init + [ + "hook" => "init" + "priority" => 60 + "callback" => function() { ... } + ], + + // Register an action to be performed after get_header + // Priority will default to 99 + [ + "hook" => "get_header" + "callback" => function() { ... } + ], + + // PRO TIP: Hooks can also be registered using this shorthand syntax + // Useful when priority isn't necessary + "get_header" => function() { ... } + ], +] +``` + +
Registering several hooks. The two get_header hooks will be registered in order of definition, so the first one will run before the second.
\ No newline at end of file diff --git a/content/docs/configuration/custom-post-types.md b/content/docs/configuration/custom-post-types.md index 06f6f70..b422b0b 100644 --- a/content/docs/configuration/custom-post-types.md +++ b/content/docs/configuration/custom-post-types.md @@ -8,7 +8,7 @@ images: [] menu: docs: parent: "configuration" -weight: 100 +weight: 110 toc: true --- @@ -55,30 +55,33 @@ Here is a custom post type for a TV Show with a genre taxonomy, custom labels, a
config.php
-
return [
    "custom-post-types" => [
        [
            "slug" => 'shows',
            "icon" => 'dashicons-format-video',
            "options-pages" => ['show-archive-settings'],
            "taxonomies" => ['genre'],
            "disable" => ['yoast'],
            "options" => [
                "has_archive" => 'shows',
                "show_in_nav_menus" => true,
                "supports" => ['title', 'editor', 'thumbnail'],
                "rewrite" => [
                    'slug' => 'shows',
                    'with_front' => true,
                    'pages' => true,
                    'feeds' => true,
                ],
                "labels" => [
                    'name' => _x('TV Shows', 'Post Type General Name', 'text_domain'),
                    'singular_name' => _x('TV Show', 'Post Type Singular Name', 'text_domain'),
                ]
            ]
        ],
    ]
]
A new custom post type with the slug "shows" +``` + +A new custom post type with the slug "shows" diff --git a/content/docs/configuration/disable.md b/content/docs/configuration/disable.md index 910a972..809a69c 100644 --- a/content/docs/configuration/disable.md +++ b/content/docs/configuration/disable.md @@ -8,7 +8,7 @@ images: [] menu: docs: parent: "configuration" -weight: 190 +weight: 120 toc: true --- @@ -24,22 +24,26 @@ Where `"disable"` is an array of strings selected from the options below. ## Options -| Key | Description | -| -------------- | ------------------------------------------------------------------------------------------------------------------------ | -| `"editor"` | Disables WordPress's editor on the admin page. Helpful if you don't want people breaking your theme. | -| `"customizer"` | If you aren't enabling fields in the admin customizer, you might as well remove the link and functionality. | -| `"gutenberg"` | This will take you back to the standard WYSIWYG editor instead of the new block editor. Helpful for strict site designs. | +| Key | Description | +| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `"editor"` | Disables WordPress's editor on the admin page. Helpful if you don't want people breaking your theme. | +| `"customizer"` | If you aren't enabling fields in the admin customizer, you might as well remove the link and functionality. | +| `"gutenberg"` | This will take you back to the standard WYSIWYG editor instead of the new block editor. Helpful for strict site designs. | +| `"emojis"` | Disables WordPress automatic [emoticon to emoji conversion](https://wordpress.com/support/emoji/#list-of-emoticons-that-convert-to-emoji) in the editor (e.g. ":)" to "🙂"). | +| `"revisions"` | Disables revision history. | +| `"meta-generator"` | Disables the `` tag generated by `wp_head()`. Recommended for site security. | {.table .table-bordered .col1-nowrap} ## Example
config.php
-
return [
    ...
    "disable" => ["editor", "customizer", "gutenberg"],
    ...
]
+```
Disabling the WordPress editor
diff --git a/content/docs/configuration/enable.md b/content/docs/configuration/enable.md index 1c48140..ec57407 100644 --- a/content/docs/configuration/enable.md +++ b/content/docs/configuration/enable.md @@ -8,7 +8,7 @@ images: [] menu: docs: parent: "configuration" -weight: 180 +weight: 130 toc: true --- @@ -28,16 +28,18 @@ Where `"enable"` is an array of strings selected from the options below. | ------------------- | ------------------------------------------------------------------------------------------------------------------- | | `"post-thumbnails"` | Enables [post thumbnails](https://codex.wordpress.org/Post_Thumbnails) | | `"menus"` | Enables WordPress menus. Individual menus can be registered using the [`menu-locations`](../menu-locations) option. | -| `"styleselect"` | Enables custom tinyMCE styles, declared [here](../tinyMCEAdditions) | +| `"styleselect"` | Enables custom tinyMCE styles, declared [here](../tinyMCEAdditions) | +| `"svg"` | Enables uploading SVGs in WordPress Admin | {.table .table-bordered .col1-nowrap} ## Example
config.php
-
return [
  "enable" => ["post-thumbnails","menus"]
]
+```
Enabling menus and post thumbnails in your theme
\ No newline at end of file diff --git a/content/docs/configuration/excerpt-length.md b/content/docs/configuration/excerpt-length.md index e2b8ff3..e2a4d33 100644 --- a/content/docs/configuration/excerpt-length.md +++ b/content/docs/configuration/excerpt-length.md @@ -7,7 +7,7 @@ images: [] menu: docs: parent: "configuration" -weight: 170 +weight: 140 toc: true --- @@ -24,9 +24,10 @@ An excerpt is an optional text associated to a Post, often used as a summary. Th
config.php
-
return [
  "excerpt-length" => 100,
]
+```
Setting the excerpt length to 100 characters.
\ No newline at end of file diff --git a/content/docs/configuration/flex-file-prefix.md b/content/docs/configuration/flex-file-prefix.md new file mode 100644 index 0000000..5b30b3d --- /dev/null +++ b/content/docs/configuration/flex-file-prefix.md @@ -0,0 +1,33 @@ +--- +title: "flex-file-prefix" +member: true +lastmod: 2020-10-13T15:21:01+02:00 +draft: false +images: [] +menu: + docs: + parent: "configuration" +weight: 150 +toc: true +--- + +Defines the prefix to use when searching for handlebars templates to render for ACF Flex content fields. Defaults to `flex`. + +## Usage + +| Key | Type | Required | Default | +| -------------------- | -------- | -------- | ------- | +| `"flex-file-prefix"` | `string` | No | `flex` | + + +## Example + +
config.php
+ +```php +return [ + "flex-file-prefix" => "acf_block", +] +``` + +
Files used as templates for ACF flex field blocks will be prefixed with 'acf_block'.
\ No newline at end of file diff --git a/content/docs/configuration/guest-class.md b/content/docs/configuration/guest-class.md index 7c05e37..bfb5a71 100644 --- a/content/docs/configuration/guest-class.md +++ b/content/docs/configuration/guest-class.md @@ -27,10 +27,11 @@ To remove this functionality altogether, set to `"null"`
config.php
-
return [
    "guest-class" => "my-custom-class",
]
+```
Setting a custom guest class
@@ -38,7 +39,8 @@ Also note that we must call the `body_class()` (or `get_body_class()`) function
header.php
-
<?php wp_head() ?>
 
<body <?php body_class() ?>>
}} +> +``` diff --git a/content/docs/configuration/handlebars.md b/content/docs/configuration/handlebars.md index 93b8025..672b491 100644 --- a/content/docs/configuration/handlebars.md +++ b/content/docs/configuration/handlebars.md @@ -8,7 +8,7 @@ images: [] menu: docs: parent: "configuration" -weight: 120 +weight: 170 toc: true --- @@ -37,7 +37,8 @@ In my `helpers/ShowHelpers.php` file, for example, I wrote this function to gene
helpers/ShowHelpers.php
-
# All of your helpers across multiple files should use the same namespace.
namespace ThemeHelpers;
 
class ShowHelpers
{
    public static function ratingBar()
    {
        return function ($template, $context, $args, $source) {
            $params = explode(" ", $args);
            $r = floatval($context->get($params[0]));
            $b = $params[1];
            $c = $params[2];
            $str = "";
            foreach (range(1, floor($r * $b)) as $number) {
                $str .= "$c";
            }
            foreach (range(ceil($r * $b), ($b * 5)) as $number) {
                $str .= "$c";
            }
            return $str;
        };
    }
}
+```
Writing a custom helper
@@ -74,7 +75,8 @@ Since we're using a custom namespace to declare our functions, we'll use Compose
composer.json
-
{
    "require": {
        "open-function-computers-llc/rad-theme-engine": "^1.0"
    },
    "autoload": {
        "psr-4": {
            "ThemeHelpers\\": "helpers/"
        }
    }
}
+```
Updating Composer's autoload to include our custom helpers
@@ -102,15 +104,16 @@ Now in our `config.php` file we can add the following:
config.php
-
return [
    "handlebars" => [
        "additional-helpers" => [
            "ratingBar" => ThemeHelpers\ShowHelpers::ratingBar(),
        ],
    ],
    ...
]
+```
Registering our custom handlebars helper
@@ -120,23 +123,23 @@ From now onwards, we can use this new helper in any of our templates by calling
tpl/show_list.tpl
-
<div class="four-col-grid">
    {{#each shows}}
    <div>
        <a href="{{url}}">
            <img class="full-image" src="{{img}}">
            <span>{{title}}</span>
        </a>
        <span class="show-item-sub-title">
            {{rating}}/5&nbsp;
            <!-- Implement my helper -->
            {{#ratingBar rating 2 ▰}}
        </span>
    </div>
    {{/each}}
</div>
+ +```
Using our new helper in a handlebars file
@@ -162,18 +165,19 @@ This is a theme configuration with a couple additional helpers, a custom `.view`
config.php
-
return [
"handlebars" => [
        "additional-helpers" => [
            "ratingBar" => ThemeHelpers\ShowHelpers::ratingBar(),
            "breadcrumbs" => ThemeHelpers\GlobalHelpers::breadcrumbs(),
            "num" => ThemeHelpers\GlobalHelpers::num(),
            "asset" => ThemeHelpers\GlobalHelpers::asset(),
        ],
        "template-extension" => "view",
        "template-directory" => "views",
    ],
]
+```
A theme with several helpers and a custom template extension/directory.
\ No newline at end of file diff --git a/content/docs/configuration/menu-locations.md b/content/docs/configuration/menu-locations.md index f9345ac..9736835 100644 --- a/content/docs/configuration/menu-locations.md +++ b/content/docs/configuration/menu-locations.md @@ -7,7 +7,7 @@ images: [] menu: docs: parent: "configuration" -weight: 130 +weight: 180 toc: true --- @@ -25,12 +25,13 @@ The `key` of the item will act as the identifier (like a slug) and the `value` w
config.php
-
return [
    "menu-locations" => [
        "main-nav" => "Main Navigation",
        "footer-nav" => "Footer Navigation",
    ],
]
+```
Registering two custom menu locations
\ No newline at end of file diff --git a/content/docs/configuration/options-pages.md b/content/docs/configuration/options-pages.md index fd7177e..1005714 100644 --- a/content/docs/configuration/options-pages.md +++ b/content/docs/configuration/options-pages.md @@ -7,7 +7,7 @@ images: [] menu: docs: parent: "configuration" -weight: 110 +weight: 190 toc: true --- @@ -29,12 +29,13 @@ To register an options page under a custom post type, see the [`custom-post-type
config.php
-
return [
    "options-pages" => [
        "general-options",
        "theme-options"
    ],
]
+```
Registering two custom ACF Pro options pages
\ No newline at end of file diff --git a/content/docs/configuration/shortcodes.md b/content/docs/configuration/shortcodes.md new file mode 100644 index 0000000..c22f16e --- /dev/null +++ b/content/docs/configuration/shortcodes.md @@ -0,0 +1,50 @@ +--- +title: "shortcodes" +member: true +lastmod: 2020-10-13T15:21:01+02:00 +draft: false +images: [] +menu: + docs: + parent: "configuration" +weight: 200 +toc: true +--- + +An array of [WordPress shortcodes](https://codex.wordpress.org/Shortcode_API) to register, where the key is the name of the shortcode and the value is the callback function. + +## Usage + +| Key | Type | Required | Default | +| ------------------ | ------- | -------- | ------- | +| `"shortcodes"` | `array` | No | `[]` | + +The `key` of the item will act as the identifier and the `value` will be the callback function. + +## Example + +
config.php
+ +```php +return [ + "shortcodes" => [ + + // [gallery id="5432" size="small"] + + "gallery" => function ($atts) { + + // Grab attributes, providing a default + // for 'size' if it's not set. + $a = shortcode_atts(array( + 'size' => 'medium', + ), $atts); + + // HTML output + // Hint: use site()->render(...) to templatize + return "gallery id = {$a['id']}"; + }, + ], +] +``` + +
Registering a custom shortcode under the name 'gallery'.
\ No newline at end of file diff --git a/content/docs/configuration/tiny-mce-additions.md b/content/docs/configuration/tiny-mce-additions.md index c8006fb..6e6bc5b 100644 --- a/content/docs/configuration/tiny-mce-additions.md +++ b/content/docs/configuration/tiny-mce-additions.md @@ -8,7 +8,7 @@ images: [] menu: docs: parent: "configuration" -weight: 140 +weight: 210 toc: true --- @@ -46,17 +46,18 @@ This custom format will apply the `custom-checkbox-list` class to all `