DOCSEARCHbyAlgolia
Submit Docs

Stellar Theme for Hexo

repository·main·Indexed 24 days ago

https://github.com/xaoxuu/hexo-theme-stellar

An elegant and powerful theme for Hexo (v6.3.0+) that transforms static blogs into multi-functional platforms. It includes built-in systems for wikis, columns, and note-taking, alongside dynamic data components like automated friend links and remote Markdown rendering. Features include modular design, multi-author support, and advanced image processing with lazy loading and automatic ratio fixing.

Tokens
4.6K
Snippets
5
Records
26
Agent score
84%

What's inside hexo-theme-stellar

  1. Overview of Stellar Theme Features

    main

    Stellar is a comprehensive Hexo theme designed for multiple use cases including blogs, knowledge bases (Wiki), columns (series), and note-taking systems.

    Key Capabilities:

    • Multi-style Layouts: Supports different layout styles for technical vs. lifestyle articles.
    • Built-in Systems: Includes a Wiki system for documentation, a Column system for immersive series reading, and a Note system.
    • Dynamic Data Components: Enables dynamic updates without full redeployment, such as:
      • Dynamic Timeline: Post short updates or subscribe to others' timelines.
      • Automated Friend Links: Automatically detects link status, tags, and subscribes to friend articles.
      • Remote Markdown Rendering: Renders remote files (e.g., a project's README) directly.
    • Modular Design: Highly reusable small components and tags that can be mixed and nested.
    • Multi-Author Support: Supports multiple authors per site, with dedicated homepages for each.
    • Image Optimization: Features lazy loading with fixed aspect ratios to prevent layout shifts.

  2. Install and Setup Stellar Theme

    main

    To use the Stellar theme with Hexo, ensure your environment meets the requirements, update your Hexo configuration, and install the package via npm.

    Prerequisites

    • Hexo: 6.3.0 to latest
    • hexo-cli: 4.3.0 to latest
    • node: 14.17.3 to latest LTS (LTS versions are recommended for compatibility)
    • npm: 6.14.13 to latest

    Installation Steps

    1. Set the theme in your Hexo _config.yml:
      theme: stellar
    2. Install the theme using npm:
      npm i hexo-theme-stellar
    npm i hexo-theme-stellar

  3. Automatic image lazy loading and error handling

    main

    Stellar automatically registers two Hexo filters to enhance image behavior in the rendered HTML:

    1. Lazy Loading: Uses img_lazyload to process the site content after HTML rendering, enabling lazy loading for images.
    2. Error Handling: Uses img_onerror to process the site content after HTML rendering, providing fallback mechanisms if an image fails to load.

    These are registered to the after_render:html hook and do not require manual configuration by the user.

  4. Use the {% image %} markdown tag

    main

    The Stellar theme provides a custom {% image %} markdown tag for advanced image processing, including sizing, background colors, aspect ratios, downloads, and Fancybox integration.

    Syntax: {% image src [alt] [width:400px] [bg:#eee] [download:true/false/url] [fancybox:true/false/url] [ratio] %}

    Parameters:

    • src: The source URL or path of the image.
    • alt: The alternative text for the image, which also serves as the caption and Fancybox description.
    • width: Sets the image width (e.g., width:400px).
    • height: Sets the image height.
    • bg: Sets the background color (e.g., bg:#eee).
    • padding: Sets the padding around the image.
    • download: Enables a download link.
      • true: Downloads the original src.
      • false: Disables download.
      • [url]: Uses the provided URL for the download.
    • fancybox: Enables Fancybox lightbox integration.
      • true: Enables standard Fancybox.
      • false: Disables Fancybox.
      • [url]: Uses the provided URL as the lightbox target.
    • ratio: Sets the aspect-ratio for the image container (e.g., ratio:16/9).

  5. Use the {% sites %} markdown tag

    main

    The {% sites %} tag allows you to display a collection of websites or projects. It supports three modes of operation based on the arguments provided: fetching data from a remote API, fetching data from a GitHub repository, or displaying a predefined group of links from your theme configuration.

    Argument Syntax

    Arguments are space-separated. Optional parameters are enclosed in brackets in documentation but should not be included in the actual tag.

    • group: Displays a list of sites defined in your _config.yml under the links key using the specified group name.
    • repo:owner/repo: Fetches site data from a JSON file located at https://<api_host>/owner/repo/output/v2/data.json.
    • api:http: Fetches site data from a custom API URL.

    Usage Examples

    Display a predefined group of links:

    {% sites my-group %}

    Fetch data from a GitHub repository:

    {% sites repo:username/project-repo %}

    Fetch data from a custom API:

    {% sites api:https://api.example.com/sites.json %}
    {% sites [group] [repo:owner/repo] [api:http] %}

  6. Use the OKR markdown tag

    main

    The okr tag allows you to display Objectives and Key Results (OKR) in your Hexo posts using a structured markdown syntax. It supports an Objective (O) and multiple Key Results (KR) with progress percentages and status indicators.

    Syntax Structure

    1. Objective: Defined using the {% okr ... %} tag. It requires an identifier (e.g., o1) and accepts optional parameters like percent, status, and color.
    2. Objective Content: The first line after the opening tag is the title, and subsequent lines are the note (rendered as markdown).
    3. Key Results: Defined using HTML comments <!-- okr kr1 ... -->. Each KR requires an identifier (e.g., kr1) and accepts optional parameters like percent and status.
    4. KR Content: The first line after the KR comment is the title, and subsequent lines are the note.
    5. Closing: The block must end with {% endokr %}.

    Parameters

    • percent: A numeric value representing progress (e.g., percent:50).
    • status: One of in_track, at_risk, off_track, finished, or unfinished.
    • color: A color identifier (mapped via theme configuration).

    If percent is not provided for the Objective, it is automatically calculated as the average of all its Key Results' percentages.

  7. Use `stellar.initPage` to handle PJAX navigation

    main

    Because Stellar uses PJAX for smooth page transitions, standard DOM event listeners may not re-trigger on new content. You must re-initialize the theme's interactive components by calling stellar.initPage() inside a pjax:complete event listener.

    document.addEventListener('pjax:complete', function () {
  stellar.initPage();
});

  8. Enable Markdown image parsing to Stellar image tags

    main

    The theme can automatically convert standard Markdown image syntax ![alt](url "title") into Stellar's internal {% image url title %} tag format. This is useful if you want to leverage Stellar's specific image processing features (like lazy loading or specific styling) while writing standard Markdown.

    To enable this, set tag_plugins.image.parse_markdown to true in your Hexo theme configuration (_config.stellar.yml).

    Note: The parser is designed to ignore images located inside code blocks (```) or inside {% gallery %} blocks to prevent accidental conversion of code examples.

  9. Configure album links in theme config

    main

    To use the {% albums group %} syntax, you must define the link groups in your theme configuration file (usually _config.stellar.yml or similar). Each group contains an array of objects representing the album items.

    Each item in the array can include:

    • url: The destination link (required for the item to render).
    • title: The caption displayed below the image.
    • cover / icon / avatar: The image source for the album card. If none are provided, the theme's default.cover is used.

    Example configuration structure:

    links:
  friends:
    - url: "https://example.com"
      title: "Friend Name"
      cover: "/images/friend1.jpg"
    - url: "https://another.com"
      title: "Another Friend"
      icon: "/images/icon1.png"

  10. Configure Fancybox and Image defaults

    main

    The {% image %} tag behavior can be controlled via the theme configuration.

    • Fancybox Global Enable: Controlled by plugins.fancybox.enable.
    • Fancybox Tag Default: Controlled by tag_plugins.image.fancybox.
    • Error Handling: If an image fails to load, the theme uses the fallback image defined in default.image_onerror.
    • Loading State: The loading placeholder is defined in default.loading.

  11. Enable automatic image ratio fixing in development

    main
    To enable automatic image ratio generation and Markdown image tag fixing during development, set the dependencies.lazyload.fix_ratio option to true in your Hexo theme configuration. This feature only activates when running Hexo in development mode (e.g., hexo server or hexo s).

  12. Configure friend groups in _config.yml

    main

    To use the group parameter with the {% friends %} tag, you must define a links object in your theme configuration. Each group is an array of objects containing title, url, and optionally icon or avatar.

    Configuration Structure:

    links:
  group_name:
    - title: "Friend Name"
      url: "https://example.com"
      icon: "https://example.com/icon.png"
    - title: "Another Friend"
      url: "https://other.com"
      avatar: "https://other.com/avatar.png"

    If icon or avatar is not provided, the theme will fall back to the default.avatar setting defined in your configuration.