Astro Configuration

A couple reasons on why you may want to change sections of the built-in Astro configuration is both updating the Table of Contents and Open Graph elements, as they’re both added as integrations here.

It’s also recommend that you copy the existing Astro configuration file that was already included with ButterflyVu and start modifying it from there.

• Don’t remove any existing imports.

• Don’t change the adapter as it should remain as deno() since the Docker image was built using denoland/deno:alpine. Other adapters like Node and Bun won’t work in this situation, unless you were to go in and rebuild the ButterflyVu image using your own Dockerfile.

• Don’t change the server entry point as it should remain as vu.mjs, the Docker image was built to point to this server entry file to launch.

• Don’t change the public directory as ButterflyVu was structured to relocate it’s public directory to src.

Other options may be added, removed, or changed freely.

To Override

In order to override the Astro configuration, add the following volume to compose.yml:

...
volumes:
    - ./overrides/astro.config.mjs:/vu/astro.config.mjs
...

Table of Contents Integrations

The Table of Contents(TOC) element is built within the configuration file and set within the customToc options under integrations.

The customToc options can be re-configure to change it’s template, maxDepth, and order.

Template - template

A function that takes the generated HTML and returns the final HTML. This can be used to wrap the generated HTML in a custom template.

All content that is generated by the page content should be put in ${html}.

const defaultTemplate = (html) => {
	return `
<aside class="toc">
    <h2>Contents</h2>
    <nav>
        ${html}
    </nav>
</aside>`.trim()
}

const VuTOC = (html) => {
	return `
        <div data-mobile="false"  class="voc-container">
            <div class="vu-toc-items">
                ${html}
            </div>
        </div>
        <details data-mobile="true" class="voc-container">
            <summary>Table of Content</summary>
            <div class="vu-toc-items">
                ${html}
            </div>
        </details>
        <style is:inline>
        @media screen and (max-width: 1400px) {
            .voc-container[data-mobile="false"] {display: none}
            .voc-container {
                position: inherit !important;
            }
            .vu-toc-items {
                position: inherit !important;
                background: black;
                border-radius: 12px;
                margin-top: 24px;
                width: 100% !important;
                font-size: 16px !important;
                padding: 12px 0px 1px 0px;
            }
        }
        @media screen and (min-width: 1400px) {.voc-container[data-mobile="true"] {display: none}}
        .voc-container {
            position: sticky;
            top: 0;
        }
        .vu-toc-items {
            font-size: 14px;
            position: absolute;
            left: 100%;
            width: max-content;
            ul {padding-left: 16px}
            li {
                list-style: none;
                background: transparent;
                border-left: 2px transparent solid;
                &:hover {border-left: 2px white solid}
                a {
                    color: #aaa;
                    padding: 3px 12px;
                    display: block;
                    &:hover {text-decoration: none}
                }
            }
        }
        </style>
    `
}

Max Depth - maxDepth

The maximum depth of headings to include in the table of contents.

Default: 3

Order - order

Whether to use an ordered list (<ol>) or an unordered list (<ul>).

Default: false

All options explained here are also shown on the astro-custom-toc GitHub repository.

Open Graph Integrations

The Open Graph configuration for solid color background, size, scale, and fonts are set within the opengraphImage options under integrations.

Background - background

Choose whatever color you want your background to be.

Default: #000000

Width and Height - width / height

Adjust the size of your embed image. The size 1200x630 is a good start across platforms.

Default width: 1200

Default height: 630

Scale

Adjust scale of embed.

Default: 3

Fonts - fonts

The fonts option is an array of options that allow you to choose custom fonts that’ll be included within the Open Graph. By default, ButterflyVu already includes Red Hat Text font for regular and bold variants.

opengraphImage({
	background: "#000000",
	width: 1200,
	height: 630,
	scale: 1,
	fonts: [
		{
			name: "RedHatText",
			data: await readFile("src/public/fonts/RedHatTextVF.woff"),
			style: "normal",
			weight: 400,
		},
		{
			name: "RedHatText",
			data: await readFile("src/public/fonts/RedHatText-Bold.woff"),
			style: "normal",
			weight: 700,
		},
	],
})