Skip to content

Basic Configuration

· 5 min

This post is an basic guide on how to configure the src/config.ts file. If you’ve already set it up or feel confident configuring it (a simple task with type hints appearing on hover), you can skip ahead to Advanced Configuration.

Configuring SITE#

The SITE object is used to configure the basic information of your website, and its configuration options are as follows:

OptionsTypeDescriptionExample
websitehttp://${string} | https://${string}Specifies the final deployed URL, which must start with http:// or https://. It will be passed to the site config in Astro,
used for generating canonical URLs, rss.xml and other features.
'https://example.com'
base/${string}Specifies the base path for your site, which must start with /. It wiil be passed to the base config in Astro, used when deploying to a subdirectory./my-site/ (for a site deployed to https://example.com/my-site/)
titlestringSpecifies the site name for formatting the title in the frontmatter as <pageTitle> - <siteTitle>.Maybe Use Your Name
descriptionstringSpecifies the default content for meta tags.Introduce yourself
authorstringSpecifies your name for meta tags.Your Name
langstringSpecifies the primary language of the document content. It must be a single ‘language tag’ in the format defined in RFC 5646: Tags for Identifying Languages (also known as BCP 47).'zh-Hant' (Chinese written using the Traditional Chinese script)
'fr' (French)
ogLocalestringSpecifies the page content’s language and region for better content display on social platforms. It must be in language_TERRITORY format, which you can find in Language-Territory Information.'zh_CN'
'fr_FR'
Ensure site.website Is Edited before Deploying!

During development, leaving SITE.website empty is fine. But in production, you must set your deployed URL in this option for SEO-related elements like canonical URLs and social card URLs.

Configuring UI#

The UI object allows you to configure navigation, social links, page views, and more. Its configuration options are as follows:

OptionTypeDescription
internalNavsInternalNav[]Configures internal navigation links. The configuration order matches the display order.
socialLinksSocialLink[]Configures external social links. The configuration order matches the display order.
NavBarLayoutNavBarLayoutControls the layout of the navigation bar.
tabbedLayoutTabsfalse | [Tab, Tab, ...Tab[]]Enables and configures for tabs within a tabbed layout. If your website does not use the TabbedLayout, you can set it to false. Otherwise, required before using this layout.
groupViewGroupViewConfigures the /projects UIs.
githubViewGitHubViewConfigures the /releases and prs UIs.

InternalNav#

The properties of the InternalNav configuration are as follows:

PropertyTypeDescriptionExample
path/${string}Specifies the navigation path. It must start with /.'/blog''/blog/'
titlestringSets the content displayed on hover for accessibility.'Blog'
displayMode'alwaysText' | 'alwaysIcon' | 'textHiddenOnMobile' | 'iconHiddenOnMobile' | 'textToIconOnMobile'Defines how the navigation item is displayed responsively. Different modes control the visibility of text or icon depending on the viewport size.'textToIconOnMobile'
textstringSets the text displayed for the navigation item. Required for displayMode values 'alwaysText', 'textHiddenOnMobile', and 'textToIconOnMobile'.'Blog'
iconIconSets the icon displayed for the navigation item. Required for displayMode values 'alwaysIcon', 'iconHiddenOnMobile', and 'textToIconOnMobile'.'i-ri-article-line'
(The icon format follows the i-<collection>-<icon> or i-<collection>:<icon> format as per UnoCSS specs. See Icon Usage for details on setting up icons)

The properties of the SocialLink configuration are as follows:

PropertyTypeDescriptionExample
linkhttp://${string}` | `https://${string}Set the URL to the social platform.'https://x.com/astrodotbuild'
titlestringSets the content displayed on hover for accessibility.Follow ${SITE.author} on Twitter
displayMode'alwaysText' | 'alwaysIcon' | 'textHiddenOnMobile' | 'iconHiddenOnMobile' | 'textToIconOnMobile'Defines how the social item is displayed responsively. Different modes control the visibility of text or icon depending on the viewport size.'alwaysIcon'
textstringSets the text displayed for the social item. Required for displayMode values 'alwaysText', 'textHiddenOnMobile', and 'textToIconOnMobile'.'GitHub'
iconIconSets the icon displayed for the social item. Required for displayMode values 'alwaysIcon', 'iconHiddenOnMobile', and 'textToIconOnMobile'.'i-ri-article-line'
(The icon format follows the i-<collection>-<icon> or i-<collection>:<icon> format as per UnoCSS specs. See Icon Usage for details on setting up icons)

The properties of the NavBarLayout configuration are as follows:

PropertyTypeDescriptionExample
leftNavBarComponentType[]Defines which components (‘internalNavs’, ‘socialLinks’, ‘searchButton’, ‘themeButton’, ‘rssLink’) are positioned on the left side of the navigation bar.[] (If you want all components to appear on the right side, leave this array empty)
rightNavBarComponentType[]Defines which components (‘internalNavs’, ‘socialLinks’, ‘searchButton’, ‘themeButton’, ‘rssLink’) are positioned on the right side of the navigation bar.['internalNavs', 'socialLinks', 'searchButton', themeButton', 'rssLink'] (Components in left and right arrays must not contain duplicates)
mergeOnMobilebooleanControls whether the ‘internalNavs’ and ‘socialLinks’ section are combined into a single navigation menu on mobile, managed through a hamburger icon.true

GroupView#

The properties of the GroupView configuration are as follows:

PropertyTypeDescriptionExample
maxGroupColumns2 | 3Sets the maximum number of columns displayed in the group view.3
showGroupItemColorOnHoverbooleanDetermines whether group item icons display in color when hovered over. If true, the icon for the group item will display in its original colors on hover.true

GithubView#

The properties of the GithubView configuration are as follows:

PropertyTypeDescriptionExample
monorepos${string}/${string}[]Defines monorepo repositories using <owner>/<repo> format. For monorepos, the tag name is used as the primary text for /releases page.['withastro/astro'] (If you want all components to appear on the right side, leave this array empty)
mainLogoOverrides[RepoWithOwner | RegExp, Url | Icon][]Configures main logos for repositories or packages (for monorepos). Defaults to the owner’s avatar if no custom logo is set.[/starlight/, 'https://starlight.astro.build/favicon.svg'] (Prioritized by order)
subLogoMatches[RepoWithOwner | RegExp, Url | Icon][]Configures auxiliary logos for rrepositories or packages (for monorepos). No logo is shown if unmatched.[/tweet/, 'i-logos-twitter'] (Prioritized by order)

Configuring FEATURES#

The FEATURES object globally controls the activation and configuration of special features. Each feature can be managed as follows:

Share#

OptionTypeDescriptionExample
twitterFeatureConfig<Mentioned>Configures Twitter sharing. If enabled, adds a mention to the specified username.[true, '@userName']
mastodonFeatureConfig<Mentioned>Configures Mastodon sharing. If enabled, adds a mention to the specified user.[true, '[@userName@serverName](@ste7lin@fairy.id)']
facebook




booleanControls whether to include Facebook for sharing.true
pinterestbooleanControls whether to include Pinterest for sharing.true
redditbooleanControls whether to include Reddit for sharing.true
telegrambooleanControls whether to include Telegram for sharing.true
whatsappbooleanControls whether to include WhatsApp for sharing.true
emailbooleanControls whether to include Email for sharing.true

TOC#

OptionsTypeDescriptionExample
minHeadingLevel1 | 2 | 3 | 4 | 5 | 6Sets the minimum heading level. Must be less than or equal to maxHeadingLevel.2
maxHeadingLevel1 | 2 | 3 | 4 | 5 | 6Sets the maximum heading level. Must be greater than or equal to minHeadingLevel.4
displayPosition'left' | 'right'Sets the position of TOC on the page (either on the left or right).'left'
displayMode'always' | 'hover'Controls whether the TOC is always visible or only appears when hovering.'hover'

OG Image#

OptionsTypeDescriptionExample
authorOrBrandstringDefines your name or brand name that will be displayed on the OG image.'Your name'
fallbackTitlestringSets the fallback title for OG images. Used when the title in the frontmatter is missing or invalid.'Site Description'
fallbackBgType'plum' | 'dot' | 'rose' |'particle'Sets the fallback background for OG images. This value is only used for the fallback OG image and as the background when bgType is not specified.'plum'

Slide Enter Animation#

OptionsTypeDescriptionExample
enterStepnumberAdjusts the animation speed (ms). Smaller values speed up; larger values slow down.60

After making these changes, ensure the project runs smoothly in the browser before moving on to Advanced Configuration. 🧗‍♂️