Esserco_Avoink

Esserco Avoink Development Documentation

Esserco Avoink

Esserco Avoink is a modern Jekyll website template designed to provide a clean, fast and easily customizable solution for personal blogs and portfolios.

comestores & Esser

Esser means eater in German. Comestores means eater in Latin. Their combination is “Esserco”. Esserco means “I am here” in Italian.

Interestingly, the author’s ID Ganfan_man(干饭人) means “eater” in Chinese.

Avoin & link

Linus is Finnish. Avoin is Finnish for open. Combining it with “link”, Avoink means open link.

---

Quick Starts

Getting the program up and running quickly

Operational dependencies

• Ruby, ~> 3.2.0
• jekyll, ~> 4.4.0
• bundler, ~> 2.4.22
• Git (For cloning projects)

Installation with git

1. cloning projects

   git clone https://github.com/Gan-fan-man/Esserco-Avoink.git
   cd Esserco-Avoink
   

2. Installing Ruby dependencies (using Bundler)

   bundle install
   

Running Projects

Run in the project root directory

bundle exec jekyll serve

The website will be generated at http://localhost:4000

Building a website

Generate static files for the production environment:

bundle exec jekyll build

The generated site files will be located in the _site/ directory.

Feature Support

• Content Management and Publishing: This template provides a solid foundation for article publishing and custom tool integration. Its design simplifies the process of content launch.
• Clear Project Architecture and Development Guide: It has a clear project structure that is easy for users to navigate and understand. Comprehensive technical documentation will guide developers to efficiently build and customize websites.
• Integrated Plugin Ecosystem: This template is pre-integrated with extended functional plugins. For example, VideoJS Esserco Avoink TOC mathjax is designed to reduce the initial setup overhead of commonly used functions.
• Extensible Design: This template takes modularity and extensibility as core principles and supports direct customization and adjustment. Its concise code base and logical structure make it easy to expand functionality or integrate new components as needed.

Usage Guidelines

Table of Contents

• Features
  • Configuration
  • Customizing Head
  • Creating Themes
  • Home page background
  • Customizing Navigation
  • Customizing Cover Image
  • Customizing Social Links
  • Enabling Posts Archive
  • Enabling TOC
  • Enabling MathJax
• Advanced Development
  • Website Structure
  • Page Definition-tool
  • Page Definition-post
  • Unified CSS Management
  • CSS Management
• Contributing to Esserco Avoink
  • Reporting Bugs
  • Suggesting Features
  • Submitting Code

Features

• Jekyll SEO Tag
• Jekyll Feed
• Jekyll Sitemap
• Jekyll Gist
• Jemoji
• Google Analytics
• Disqus
• Font Awesome
• MathJax
• Mahoubox
• VideoJS
• Dark mode (enabled automatically via CSS media query)
• Posts archive by dates, categories, and tags
• Pagination, generated by Jekyll Paginate-V2
• TOC (generated by Vladimir “allejo” Jimenez’s jekyll-toc)
• Related posts (time-based, because Jekyll) below each post
• Easily scalable text and component sizing with rem units in the CSS
• Support for a wide gamut of HTML elements
• Syntax highlighting, courtesy Pygments (the Python-based code snippet highlighter)

Configuration

The _config.yml file in this repository already contains some variables, you can try to override them in your repository.

• title: Website’s main title, displayed globally in browser tabs and headers.
• description: Brief website description for SEO and metadata.
• url: Full website URL, crucial for absolute links and RSS feeds.
• baseurl: Subdirectory of the website, if not hosted at the domain root.
• avatar: Path to the website’s avatar image.
• cover_image: Default cover image path for pages and listings.
• pagination: Configuration for post pagination.
  • enabled: Enable or disable pagination.
  • per_page: Number of posts per page.
  • sort_field: Field to sort posts by (e.g., ‘date’).
  • sort_reverse: Sort order (true for descending).
• plugins: List of Jekyll plugins to extend site functionality.
  • jekyll-gist: Enables embedding Gist code snippets.
  • jekyll-paginate-v2: Provides advanced pagination features.
  • jekyll-seo-tag: Automates SEO metadata generation.
  • jekyll-feed: Generates RSS feeds for the site.
  • jekyll-sitemap: Generates an XML sitemap for search engines.
• exclude: Files or directories to exclude from the Jekyll build process.
• twitter: Twitter Card metadata configuration.
  • username: Twitter handle.
  • card: Type of Twitter Card (e.g., ‘summary’).
• social: List of social media links for display (e.g., in footer/sidebar).
• langs: List of supported languages for the website.
• sass: Sass compiler settings.
  • sass_dir: Directory containing Sass source files.
  • style: Output style for compiled CSS (e.g., ‘compressed’).
• author: Website author’s information.
  • name: Author’s name.
  • url: Author’s personal or GitHub URL.
  • email: Author’s email address.
• collections: Custom content collections beyond default posts.
  • tools: Defines a collection named ‘tools’.
    • output: Set to true to output collection items to the site.
    • permalink: URL structure for ‘tools’ collection items (e.g., /tools/:name/).

Customizing Head

You can customize the head section by modifying _includes/custom-head.html.

In principle, you can add anything here, such as a website icon. You just need to write the data into it.

You can use Favicon generator to generate website icons.

Creating Themes

If you want to make your own color schemes, modify the CSS variables in the _sass/_variables.scss stylesheet with a scoped data attribute or class name.

For example, below we’ve created the beginnings of a blue theme:

// Example blue theme
[data-theme="blue"] {
  --body-bg: var(--blue);
  --body-color: #fff;
}

Then, apply the theme by adding data-theme="blue" to the <html> element.

Home page background

This file _data/images.yml contains the background of the homepage of the website.

You need to fill in these files according to the full path. If the bandwidth service you use is not enough to support high-resolution images or considering that the user’s hardware configuration is often not satisfactory, I recommend you use 1080p resolution.

  - /images/home/1080/

Customizing Navigation

The file _data/navigation.yml to configure links to some pages. For example,

- title: About
  url: /about/
- title: Post
  url: /post/
- title: Tools
  url: /tool/

Customizing Cover Image

You can set your own cover image by modifying the cover_image variable in _config.yml, and you can also set different cover images on different pages by setting the cover_image variable on each page.

If you discover that the contrast between the cover text color and the cover background color is not enough, you can also adjust these two variables:

cover_bg_color: rgb(40, 73, 77)
cover_color: rgb(255, 255, 255)

Customizing Social Links

You can set your social links in _data/social.yml. You can custom titles, URLs, and icons (only support Font Awesome currently), for example:

- title: Email
  url: mailto://ganfan.man.2023@gmail.com
  icon: fas fa-envelope
- title: Twitter
  url: https://twitter.com/Ganfan_man
  icon: fab fa-twitter
- title: GitHub
  url: https://github.com/Gan-fan-man
  icon: fab fa-github

Enabling Posts Archive

Esserco Avoink supports archiving posts by date, category and tag. It is enabled by default.

If you want to adjust them you need to modify _data/archive.yml:

- type: dates
  title: Dates
  url: /dates/
- type: categories
  title: Categories
  url: /categories/
- type: tags
  title: Tags
  url: /tags/

Enabling TOC

If you want to show the TOC of a page on the right side, just set toc: true on that page.

The table of contents requires the use of

h1→h2→h3 arrangement requirements

does not allow

h1→h3

If you want to solve this problem, you can try to modify _includes/sidebar-right.html

Change

include toc.html html=content h_min=1 h_max=6 class="toc"

to

include toc.html html=content h_min=2 h_max=3 class="toc"

This can avoid the problem of incorrect display, but it will filter out level 1 titles and level 4~6 titles

Enabling MathJax

If you want to write mathematics on a POST, just set math: true on that POST to enable MathJax.

Advanced Development

Below is a detailed guide to website development. If you need to delve deeper into this project, please read these carefully. It may be helpful to you.

Website-Structure

Open the root directory and you will find these files (before the website is built)

The folders you will find are

_data             # Stores site-wide configuration data, in YAML format, for dynamic content generation (e.g., navigation, social links).
_includes         # Contains reusable snippets of HTML, Liquid, or Markdown that can be included across multiple layouts or pages.
_layouts          # Defines the structural templates for different types of pages or content.
_posts            # Houses all blog posts, organized by year, month, and day (YYYY-MM-DD-title.md).
_sass             # Stores Sass (Syntactically Awesome Style Sheets) files, which are compiled into CSS for styling the website.
_tools            # A custom collection defined, for showcasing specific tools or projects.
assets            # Stores static assets like CSS, JavaScript files, and fonts that are directly served to the browser.
images            # Dedicated folder for storing all images used throughout the website.
pages             # Contains independent pages that do not belong to the _posts or _tools collections. Defines the website display structure.
scripts           # Holds scripts used for website functionality.

_includes Folder Files

The _includes folder is a repository for modular HTML, Liquid, or Markdown snippets that can be embedded into various layouts or pages, promoting reusability and maintainability.

• content.html: Influencing the footer’s positioning and content.
• cookie.html: This file contains the HTML, CSS, and JavaScript for a multilingual cookie consent banner that appears at the bottom of the page.
• custom-head.html: Provides a designated placeholder for developers to insert custom <head> elements, such as favicons, meta tags, or third-party script includes.
• disqus.html: As the name suggests, this file integrates the Disqus comment system into relevant pages.
• google-analytics.html: Responsible for embedding the Google Analytics tracking code to monitor website traffic and user behavior.
• head.html: The global <head> section of the HTML document, containing essential metadata, stylesheets, and script links that apply to all.
• mathjax.html: Calling the MathJax library to enable rendering of mathematical equations on pages where it’s enabled.
• post-header.html: Responsible for the header display of the post page Can modify _data/archive.yml to adjust the display target
• post-tags.html: Dynamically extract tags from the article’s metadata and, depending on the site configuration, display clickable tag links or just plain text tags
• scroll.html: Control the scrolling behavior of the page, especially on mobile devices, and manage scroll state.
• sidebar-left.html: Defines the content and structure of the left sidebar, used for link display
• sidebar-right.html: Defines the content and structure of the right sidebar, used to call TOC
• toc.html: Renders the Table of Contents (TOC) for a page, dynamically generating links to its headings.

_layouts Folder Files

The _layouts folder contains the blueprint templates that define the overall structure and presentation of different types of content on the website.

• archive-dates.html: The layout specifically for displaying chronological archives of posts, organized by date.
• archive-taxonomies.html: The layout used for displaying archives based on categories or tags (taxonomies).
• base.html: A base layout that establishes the basic HTML structure. All layouts except post.html use this layout.
• default.html: This is the standard template for _posts content.
• home.html: The specific layout for the website’s main homepage.
• page.html: Common styles designed for base.html. It provides the necessary CSS and defines the main content area of ​​this type of page.
• post.html: A dedicated layout for rendering a single post, providing specific structure and elements unique to a single post view, based on default.html.
• post_home.html: This layout specifically controls how blog posts are displayed on the post home page, based on default.html.
• tool.html: A dedicated layout for rendering a single tool page, providing specific structure and elements unique to a single tool view, based on base.html.
• tool_home.html: This layout specifically controls how blog tools are displayed on the tool home page, based on base.html.

Page definition-tool

The overall structure of the tool page

The definitions of all non-homepage and article pages come from base.html.

and the CSS style of base.html is in page.html.

Therefore, all non-homepage and article pages will reference page.html as the basic style.

including tool tool_home about 404.html

In the website structure, all tools are displayed in /tool

And the url of the tool page needs to be set manually

Their headers should be like this

---
layout: tool
title: XXX
permalink: /tool/XXX/
---

Then you can freely create tools

Also note that when using the layout: tool, the system automatically creates a div block named “page” to display the content when a header is detected.

For example, test.html

Write

---
layout: tool
title: test
permalink: /tool/test/
---
<h2 style="text-align: center; margin-bottom: 20px;">A test page</h2>

When output, it will be

<article class="page">
<div class="tool-page-container">
<h2 style="text-align: center; margin-bottom: 20px;">A test page</h2>
</div>

Page definition-post

The overall structure of post

All post pages are defined in default.html.

The CSS styles for default.html are in _sass/default.scss.

Therefore, all article pages refer to default.html as their base style.

This includes post.html post_home.html archive-taxonomies.html archive-dates.html.

In the site structure, all files directly based on default.html are shown in /post.

The time of each blog post The title needs to be set manually

The jekyll-paginate-v2 plugin will act as a paginate, and according to the _config.yml setting, it will automatically sort the posts in order from newest to oldest.

The title should look like this

---
layout: post
title: testpost
date: 2000-01-01 00:01 +0800
last_modified_at: 2099-12-31 23:59:59 +0800
categories: [X]
tags: [X]
toc: true
math: true
---
A test page
{: .message }

Note that the {:.message } is not required, but if it is, it creates a simple message below the header, where you can generally write a brief description of the post.

Once you’ve set it up, you can write posts freely.

Unified CSS management

This styles.scss file serves as the main entry point for the website’s styling. It orchestrates the entire visual presentation by importing various SCSS partials, defining global styles, and managing theme-specific adjustments.

Global Variables

The stylesheet heavily relies on variables defined in _variables.scss. These variables control:

• Colors: --body-color, --link-color2, --yellow-100, --gray-900, --gray-500, etc., for consistent color schemes.
• Spacing: --spacer, --spacer-2, --spacer-3 to maintain uniform spacing throughout the layout.
• Typography: --body-font, --code-font, --body-font-size, --body-line-height for consistent font usage and readability.
• Layout: $sm-width, $md-width, $lg-width for responsive breakpoints.
• Other: --border-radius, --code-bg, and specific variables for tool sections (e.g., --tool-bg, --tool-content-bg).

Development Guide

1. Modular Approach: Styles are organized into small, thematic partials (e.g., _layout.scss, _posts.scss). This promotes modularity and makes it easier to locate and modify specific styles.
2. Variable Usage: Utilize the variables defined in _variables.scss for colors, spacing, and typography to ensure consistency and simplify theme changes.
3. Syntax Highlighting: The file includes mixins from _syntax.scss to apply light and dark syntax highlighting themes based on the user’s prefers-color-scheme setting, ensuring code readability in different environments.
4. Responsive Design: Media queries are used in partials like _layout.scss to adapt the design for various screen sizes, promoting a responsive user experience.

Extensibility

• New Partials: To add new sections or components, create a new SCSS partial (e.g., _new-component.scss) and import it into styles.scss.
• Variable Updates: Global style changes can be efficiently managed by updating the values in _variables.scss.
• Theme Customization: The use of CSS variables (e.g., var(--body-color)) and SCSS mixins for themes allows for easy customization and creation of new themes without altering core component styles.
• Component-Specific Overrides: For specific adjustments to existing components, create a dedicated SCSS file for overrides and import it, or add the styles directly to the relevant partial.

CSS Management

Below is a description of each SCSS file, outlining its scope and specific functionalities within the project.

_alignment.scss

• Scope: This file provides pre-defined SCSS classes specifically for aligning images and figcaption elements within the content.
• Specific Function: It defines classes like .align-right for right alignment, .align-left for left alignment, and .align-center for centering block-level content. It also includes specific text-align properties for figcaption elements when associated with these alignment classes.

_archive.scss

• Scope: This file contains styles exclusively for archive pages, encompassing layouts for taxonomies (categories/tags) and post lists.
• Specific Function: It styles the .taxonomies-wrapper for spacing, creates a grid layout for .taxonomies (e.g., three columns by default, two on smaller screens), and provides styling for individual .taxonomy items. It also includes styles for time elements within .post-list-by-taxonomy and for the “Back to top” link.

_code.scss

• Scope: This file defines styles for both inline and block-level code snippets, including adjustments for syntax highlighting generated by Pygments/Rouge and GitHub Gist embeds.
• Specific Function: It sets base font styles for code and pre elements, defines font size for inline code, and styles block pre elements. It also provides styles for .highlight blocks (syntax highlighting), .rouge-table (for line numbers), and specific adjustments for Gist embeds and inline plaintext code highlighted by Rouge, including dark mode variations.

_default.scss

• Scope: This file holds foundational and global styles that apply across the entire webpage.
• Specific Function: It sets box-sizing to border-box for all elements, defines global body styles (font, size, line height, colors, background). It also styles a (anchor) links and their hover/focus states, ensures responsive image behavior with consistent spacing and rounded corners, and provides base styling for table elements, td, th, and thead th. Additionally, it styles the <mark> HTML element for highlighting text.

_home-header.scss

• Scope: This file specifically defines styles for the home page header section.
• Specific Function: It controls the main #container (full viewport height), #background-container (background image sizing), and #content-container positioning. It styles the main .title with absolute positioning, custom font size, and text effects. Furthermore, it defines styles and hover effects for interactive content blocks (.div-block-1 and .div-block-2) and manages the display and transitions of .background-image elements.

_layout.scss

• Scope: This file manages the structural hierarchy and overall layout of the site.
• Specific Function: It sets basic .container styles, adjusts margins for .home-header, and defines padding, margins, and minimum height for the .content area. It styles the .sidebar-left to be a flex container with specific positioning and height. It also provides styles for footer and includes media queries to adjust content width, sidebar positioning, and visibility for different screen sizes ($md-width, $lg-width).

_message.scss

• Scope: This file defines styles for displaying alert messages to users.
• Specific Function: It provides a generic .message block style with padding, margin, specific text and background colors (e.g., var(--yellow-100)), and border-radius, applicable to single message elements or containers holding multiple messages.

_pagination.scss

• Scope: This file provides styles for blog pagination elements.
• Specific Function: It styles the main .pagination container, sets base styles for individual .pagination-item elements (both span and a tags), and defines hover states for linked pagination items. It also includes media queries to adjust the layout and appearance of pagination items for larger screens, arranging them side-by-side with appropriate borders and border-radius.

_post-header.scss

• Scope: This file contains styles for the header section of individual blog posts.
• Specific Function: It defines the styling for the post title (.post-title), including font size and text alignment. It also styles the post metadata (e.g., date, author) and any associated images within the post header, ensuring proper spacing and visual presentation.

_posts.scss

• Scope: This file is dedicated to styling the main content area of blog posts and individual post elements.
• Specific Function: It provides styling for headings (h1-h6), paragraphs, lists (ordered and unordered), blockquotes, and other textual elements within a post. It ensures consistent typography and spacing for readability.

_sidebar.scss

• Scope: This file defines the styles for the sidebar components of the website.
• Specific Function: It sets the basic layout, background, and positioning for both left and right sidebars. It also includes styling for elements commonly found in sidebars, such as navigation links, widgets, and profile information, ensuring they are visually distinct and well-organized.

_syntax.scss

• Scope: This file specifically addresses the styling of syntax-highlighted code blocks.
• Specific Function: It provides a comprehensive set of rules for different parts of code (e.g., keywords, strings, comments, variables) generated by syntax highlighters like Pygments or Rouge, ensuring readability and visual differentiation of code elements. It often defines color schemes for various token types within the highlighted code.

_toc.scss

• Scope: This file defines styles for the Table of Contents (TOC) component.
• Specific Function: It typically styles the container for the TOC, the list items within it, and the links to different sections of a page. It may include styles for nesting, active states, and general appearance to make the TOC user-friendly and visually appealing.

_type.scss

• Scope: This file is responsible for defining global typographic styles across the website.
• Specific Function: It sets default font families, sizes, line heights, and colors for various text elements like paragraphs, headings, and lists. It aims to ensure consistent and readable typography throughout the site. It may also define styles for specific text utilities such as emphasized or strong text.

_variables.scss

• Scope: This file acts as a central repository for defining SCSS variables used throughout the entire project.
• Specific Function: It stores reusable values for colors , spacing , border-radius , font families , font sizes , line heights , and various widths . By defining these in one place, it ensures consistency and makes it easy to manage and update the project’s visual style.

Contributing to Esserco Avoink

Thank you for your interest in contributing to Esserco Avoink! We appreciate your help in making this project better.

There are several ways you can contribute to this project:

• Report Bugs: Report any bugs you find.
• Suggest Features: Propose new features or enhancements.
• Fix Bugs: Fix existing bugs in the code.
• Improve Documentation: Enhance the documentation, tutorials, or examples.
• Submit Code: Add new features or improvements to the codebase.

Reporting Bugs

If you find a bug, please help us by submitting an issue on GitHub. Before submitting a new issue, please check if a similar one has already been reported.

When reporting a bug, please include the following information:

• A clear and descriptive title:
• Steps to reproduce the bug: Provide a minimal code example or a link to a demo where the bug can be seen.
• Expected behavior: What did you expect to happen?
• Actual behavior: What actually happened?
• Environment details: Include your browser version, operating system, and the version of Esserco Avoink you are using.

Suggesting Features

We welcome new ideas! If you have a feature you would like to see in Esserco Avoink, please open an issue on GitHub and label it as enhancement.

Please describe the feature in detail and explain why you think it would be a valuable addition to the plugin.

Submitting Code

Pull Requests

We are happy to accept code contributions! To ensure a smooth process, please follow these steps:

1. Fork the repository on GitHub.
2. Clone your forked repository to your local machine.

   git clone https://github.com/Gan-fan-man/Esserco-Avoink.git
   cd Esserco Avoink
   

3. Create a new branch for your changes.

   git checkout -b your-feature-name
   

   (Use a descriptive name, e.g., fix/bug-in-zoom or feat/add-new-option)

4. Make your changes:
5. Test your changes: to ensure they work as expected and do not introduce new issues.
6. Commit your changes: Use a clear and concise commit message.

   git commit -m "feat: add mouse wheel zoom functionality"
   

7. Push your branch to your forked repository.

   git push origin your-feature-name
   

8. Create a Pull Request (PR) on GitHub from your new branch.
   • Please provide a clear description of your changes in the PR.
   • Reference any related issues (e.g., “Fixes #123”).
   • Follow the PR template if one is provided.

Thank you for your contribution!

• x