GoCalf Calf 的自留地 · 昙花一现
由 AI 生成

Menus, regions and footers

Native menus

toml
[[menus.primary]]
name = 'Notes'
pageRef = '/notes'
weight = 10
[menus.primary.params]
icon = 'notebook'
color = '#ffbd2b'

Use pageRef for real internal Pages and current/ancestor highlighting. A literal URL is not a Page association. Native weights, identifiers and parent entries make up to two menu levels; a destinationless parent is a heading, a destinationless leaf is an error. Labels are authored content, not automatically translated keys. params.color is an optional hex hover/current accent, not arbitrary CSS. Empty icon hides decoration. External HTTP(S) opens a new tab with noopener/noreferrer; use explicit HTTPS, not protocol-relative URLs. No config HTML or arbitrary callbacks.

Left-sidebar menu rows use a subtle hover surface. The current page or section has a persistent accent-tinted background and its normal icon/selection indicator; hovering that selected row strengthens the tint. An entry’s params.color also controls its selected tint. Keyboard focus has a separate visible outline. Dense widget links and bottom social icons use flat hover fills, while the random article action retains a quiet resting panel. These states do not move or resize items. The right sidebar retains its own quiet surface treatment.

Optional flat social menu (up to six entries):

toml
[[menus.social]]
name = 'Email'
url = 'mailto:hello@example.org'
[menus.social.params]
icon = 'email'
[[menus.social]]
name = 'Color mode'
[menus.social.params]
icon = 'color-mode'
onclick = 'Sidera.cycleColorMode()'

Only that exact action is accepted; do not combine it with a destination. No-JS hides the inert action but retains ordinary links. The default left footer selects this menu when present. Site-owned social brand geometry can use the same icon registry; image-valued icon arguments are not supported.

Components, widgets and instances

A component is a built-in renderer. A widget is a site/language-owned configuration of one component. An instance is one placement. All regions accept names or component/config and widget/config objects; repeats are independent.

toml
[params.widgets.welcome]
component = 'text'
[params.widgets.welcome.config]
title = 'Welcome'
text = 'You are reading **{site.title}**.'
yaml
params:
  left:
    - menu
    - random
    - welcome
    - widget: recent-updates
      config: {count: 5, scope: global}
  right: [toc]
  article_footer: [terms, references, outgoing, backlinks, license, share, series]
  site_footer: [links, text, credit]

Regions are top, left, right, left_footer, article_footer, site_footer. An empty array or false disables a region and its extra hook; empty/inapplicable components leave no blank boxes. Region arrays replace rather than append through inheritance. Use native cascade for descendant choices; ordinary section params only style the section. Presets can outrank site fallback choices.

Per-use config overlays supported keys only; maps replace shallowly, explicit empty values clear, and {} means defaults rather than disable. Widgets cannot shadow built-in names or derive from widgets. Unknown/unused malformed definitions fail. See the single component option table for allowed regions/options instead of guessing a renderer’s internal fields.

Random article

The random component opens another article in the same tab, chosen uniformly from the current language across all collections, including docs and standalone pages. It appears immediately after the main menu in the general, blog, notes and docs default left sidebars, before any tag tree or page tree. Explicit region arrays still replace defaults; add random to your own list to show it, or omit it to remove it.

toml
[params]
left = ['menu', 'random', 'recent-updates']

Only published, listed regular pages with a rendered HTML destination participate; section/taxonomy indexes and link-only pages do not. Search visibility does not control participation. The current page is skipped at selection time using one shared, fingerprinted URL list per language—not a different list per article. The action is rendered disabled in the initial HTML, keeping sidebar spacing stable before scripts run and while its URL list loads. It participates in normal page-entry reveal and becomes usable when the list is ready. A no-script fallback hides it when JavaScript is disabled; it is also hidden if the list request fails or there is no other destination. With one eligible destination, it opens that page. Per-instance config.icons = false hides the arrow but keeps the label.

The default article footer includes terms, authored references, outgoing links, backlinks, license, share, series and optional text/links. Missing data disappears. The neutral default content notice says “All rights reserved unless otherwise stated”; choose your content license yourself. Sidera’s MIT software license does not change that notice or license your articles.

yaml
params:
  license: false
  share: [link, email]
  article_text: 'Thanks for reading **{page.title}**.'
  site_footer: [links, text]
  footer_menu: footer
  footer_text: 'An independently maintained notebook.'

Site footer links uses a native two-level sitemap menu; credit uses the native built_with translation. Author names appear in the article header by default. The toc sidebar component normally holds the optional edit link. Existing configurations may retain the deprecated authors footer. article_end_text is independent final Markdown after navigation/children/comments, not footer article_text.

Homepage standalone-page links and text links in footer references, license notices, authored text, build credits and the final article_end_text region use the same blue foreground, subtle underline and hover/focus highlight as body links. Footer typography remains compact. Navigation menus, tag chips, edit links and share controls keep their own interaction styles; linked images are not given text underlines or highlight backgrounds.

Share targets are link (copy with manual fallback), wechat (local build-time QR), weibo (explicit outbound share link) and email (mailto). No remote QR service or background Weibo request. Comments have their own placement, not a footer component.

Deprecated: the optional authors article-footer component remains supported for existing configurations. Prefer header author attribution and the TOC edit link for new configurations. Deprecation is documentation-only; it emits no build warning. Removal would require a future major release.

Existing article_footer: [authors] entries still show linked author names and optional profile avatars. The component accepts config.show (fallback show_authors) and config.edit_url (fallback edit_url), including named widgets, per-instance overrides and repeated instances. Explicit false/empty options keep their meaning. show: false hides the entire component, including editing; with no author or edit destination it renders nothing. Native author assignments and header visibility are independent of this optional footer placement.

When authors is explicitly selected in the effective article footer, it owns editing: the TOC does not emit a second edit action, even if the footer is hidden or its edit URL is cleared. This preserves existing visibility choices. Remove the authors entry to use the TOC action instead, and move any component-level config.edit_url to the toc instance. Site/page edit URLs can stay where they are. The default footer does not include authors.

Native overrides

Use site layouts/_partials/sidera/head-extra.html, top-extra.html, left-extra.html, right-extra.html, article-footer-extra.html or site-footer-extra.html for small additions. Context supplies Page, Owner, Region and resolved Settings. Fixed component overrides under layouts/_partials/sidera/components/ additionally receive Config, Widget, Instance, IDScope and IDSuffix; use them for unique IDs in repeated instances. Trusted templates own escaping and lifecycle. Routine menu/widget edits need no whole-layout copies or arbitrary template paths in configuration.

Edit this page

Set params.edit_url to show Edit this article in the toc component’s sidebar actions, between Back to top and Join the discussion. The default right sidebar includes toc; keep that component when customizing params.right. The edit link uses the same full-width row, 16px icon, typography and hover/focus styles as its neighboring actions. icons = false keeps the text label.

An edit URL can show the action even without body headings or comments. With no legacy authors footer selected, show_authors, sharing targets and article-footer visibility do not affect it. An empty edit URL hides only editing; existing TOC and discussion actions remain. With no headings, edit URL or comments, the component emits nothing.

On smaller screens the link is inside the page-context drawer. Without JavaScript, it remains a native link in the unenhanced sidebar. Omitting the toc component hides the TOC edit action. A selected legacy authors footer retains its own editing control instead, as described above.

For one page, set a complete destination in front matter:

yaml
params:
  edit_url: 'https://github.com/example/site/blob/main/content/notes/hello.md'

To generate links for many files, configure source-directory mappings instead:

toml
[params]
edit_url = [
  { path = '', url = 'https://github.com/example/site/blob/main/content/' },
  { path = 'manual/', url = 'https://github.com/example/theme/blob/main/docs/content/' },
  { path = 'notes/no-edit/', url = '' },
]
  • path matches Hugo’s source file path relative to the virtual content root, not the published URL. Use '' for all content or a directory ending in /. For example, notes/hello/index.md keeps index.md, even when its permalink is /welcome/. A translated file keeps its actual filename, such as hello.zh.md.
  • The longest matching prefix is replaced by url, regardless of mapping order. Matching is case-sensitive and directory-bounded; notes/ does not match notes-other/. Records keep paths as values because Hugo normalizes map keys.
  • Each nonempty mapping URL must be an absolute HTTP(S) directory URL ending in /, without a query or fragment. Sidera appends the remaining source path, escaping each filename segment (including spaces, Unicode, %, # and +). Repository, branch and destination are explicitly yours to choose. The GitHub examples use /blob/ to open the source file first, rather than jumping directly into the editor.
  • Mounts use their target path: a mount targeting content/manual matches manual/, regardless of the physical source directory. The example maps it to a different repository; it does not infer repository ownership from mounts.
  • A matching url = '' disables that subtree, even with a broader mapping. Unmatched files and generated pages (including content-adapter pages) get no mapped link.
  • Page/native cascade/preset/site precedence applies to the whole edit_url value. A page-local literal URL overrides the mapping list; '' or [] clears inherited links. The toc component/widget accepts config.edit_url with the same values, alongside config.icons; each override affects only that instance.

Literal URLs retain their existing behavior: they are used as supplied, with no path appended. Nothing fetches contributor data or calls a repository API; an edit link opens the configured destination using normal external-link behavior. Readers still need whatever access the repository requires. Disabling an edit link is presentation only, not access control.