From db16b122cf2eca2ba5e42d89dd72de921f206002 Mon Sep 17 00:00:00 2001 From: Escher WD Date: Thu, 24 Jul 2025 16:12:12 -0500 Subject: [PATCH 1/8] Use hugo/hljs over torchlight for less mess in markdown --- assets/scss/common/_variables.scss | 2 + assets/scss/components/_code.scss | 4 - assets/scss/components/_syntax.scss | 4 +- assets/scss/layouts/_docs.scss | 2 +- config/_default/config.toml | 3 + .../docs/configuration/custom-post-types.md | 43 +-- content/docs/configuration/disable.md | 7 +- content/docs/configuration/enable.md | 7 +- content/docs/configuration/excerpt-length.md | 7 +- content/docs/configuration/guest-class.md | 14 +- content/docs/configuration/handlebars.md | 70 ++-- content/docs/configuration/menu-locations.md | 11 +- content/docs/configuration/options-pages.md | 7 +- .../docs/configuration/tiny-mce-additions.md | 15 +- .../advanced-installation.html | 59 ++-- .../docs/getting-started/installation.html | 16 +- content/docs/guides/assets.md | 24 +- content/docs/guides/configuration.md | 104 +++--- content/docs/guides/handlebars.md | 141 ++++++-- content/docs/guides/taxonomies.md | 83 ++--- content/docs/guides/the-site-object.md | 47 +-- content/docs/reference/getAssetURL.md | 5 +- content/docs/reference/getDefaultPosts.md | 37 +- content/docs/reference/getPaginationLinks.md | 36 +- content/docs/reference/getPost.md | 41 +-- content/docs/reference/getPostTaxonomy.md | 24 +- content/docs/reference/getPosts.md | 53 +-- content/docs/reference/getTerm.md | 25 +- content/docs/reference/render.md | 5 +- content/docs/reference/renderMenu.md | 19 +- content/docs/reference/setPostMeta.md | 14 +- layouts/{_default => }/_markup/.gitkeep | 0 layouts/_markup/render-codeblock.html | 3 + layouts/partials/head/script-header.html | 35 ++ package.json | 1 + yarn.lock | 322 +++++------------- 36 files changed, 655 insertions(+), 635 deletions(-) rename layouts/{_default => }/_markup/.gitkeep (100%) create mode 100644 layouts/_markup/render-codeblock.html 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..59ce571 100644 --- a/assets/scss/components/_syntax.scss +++ b/assets/scss/components/_syntax.scss @@ -7,8 +7,8 @@ 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; } 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/content/docs/configuration/custom-post-types.md b/content/docs/configuration/custom-post-types.md index 06f6f70..a42294a 100644 --- a/content/docs/configuration/custom-post-types.md +++ b/content/docs/configuration/custom-post-types.md @@ -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..2659750 100644 --- a/content/docs/configuration/disable.md +++ b/content/docs/configuration/disable.md @@ -35,11 +35,12 @@ Where `"disable"` is an array of strings selected from the options below.
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..a632901 100644 --- a/content/docs/configuration/enable.md +++ b/content/docs/configuration/enable.md @@ -35,9 +35,10 @@ Where `"enable"` is an array of strings selected from the options below.
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..8499b89 100644 --- a/content/docs/configuration/excerpt-length.md +++ b/content/docs/configuration/excerpt-length.md @@ -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/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..148185e 100644 --- a/content/docs/configuration/handlebars.md +++ b/content/docs/configuration/handlebars.md @@ -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..6d4a2a0 100644 --- a/content/docs/configuration/menu-locations.md +++ b/content/docs/configuration/menu-locations.md @@ -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..40274c0 100644 --- a/content/docs/configuration/options-pages.md +++ b/content/docs/configuration/options-pages.md @@ -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/tiny-mce-additions.md b/content/docs/configuration/tiny-mce-additions.md index c8006fb..b576b52 100644 --- a/content/docs/configuration/tiny-mce-additions.md +++ b/content/docs/configuration/tiny-mce-additions.md @@ -46,17 +46,18 @@ This custom format will apply the `custom-checkbox-list` class to all `