Eyvan

Eyvan — marked by the A1 logo (pronounced /ey-van/) — is a visually minimalist, feature-rich Jekyll template inspired by the eyvan or ayvan, an open threshold space in Iranian architecture.

The template is designed for personal portfolios, academic profiles, research notes, project archives, and long-form technical writing. Its interface is restrained, but the template includes a complete publishing system: layouts, reusable Liquid includes, Sass architecture, JavaScript interactions, tag archives, social sharing, MathJax, media figures, and GitHub Actions deployment.

Live demo: Eyvan

The demo also turns on search and Google Analytics with its consent banner. Both are off in _config.yml, so a site made from this template starts without them.

Using as a Template

1. Click "Use this template" and name your new repository.

   • For a personal site: name it [your-username].github.io
   • For a project site: name it anything (e.g. my-portfolio)

2. Go to Settings → Pages → Source and select GitHub Actions. Eyvan deploys via its own workflow — the native Pages builder will not work.

3. Edit _config.yml and replace the demo identity and URL values. Choose the url and baseurl pair for your hosting type in Deployment.

4. Edit _data/author.yml and _data/footer.yml with your name and details, and replace the template's wording in the front matter of the five top-level pages (see Setting Up Eyvan).

5. Push — the deploy workflow runs automatically and your site goes live.

If any placeholder values remain after your first push, the deploy log will show warnings in the Check Template Identity step to guide you.

Features

• Responsive, content-first layouts for phones, tablets, and desktop screens
• Light/dark theme toggle with early theme initialization
• Homepage hero driven by _data/hero.yml and _data/author.yml
• A deliberately unified content model: posts serve as both writing and project entries, with a Projects archive and tag pages instead of a separate collection
• Responsive table of contents for opted-in posts: a sticky sidebar on desktop and an accessible toolbar and full-screen overlay panel on mobile and tablet screens, demonstrated in Eyvan Design and Architecture
• Optional cover images, post-card images, Open Graph, and Twitter/X preview images
• Cover crop alignment through the optional image_position front matter field
• Optional bandwidth-efficient image variants for covers, page images, and prose figures through srcset and sizes
• MathJax support for LaTeX-style math when math: true
• Reusable Liquid includes for figures, image grids, video, audio, table captions, and references
• Numbered tables and figure-like media, with optional cross-references when crossrefs: true
• Accessibility safeguards and automated Playwright/axe testing for rendered pages
• Detailed, task-focused documentation supplied as removable demo posts
• Estimated reading time controlled globally through read_time and words_per_minute in _config.yml, with an optional per-post read_time_override
• Optional full-text search of posts when search: true, built by Pagefind and served from your own site
• Optional Google Analytics that loads only after a visitor accepts a consent banner, with the banner's text in _data/analytics.yml
• A weekly external link check that reports dead links in posts without blocking merges or deploys
• Syntax-highlighted code blocks via Rouge
• Tag archive pages powered by jekyll/tagging
• SEO sitemap via jekyll-sitemap
• Atom/RSS feed at /feed.xml via jekyll-feed, auto-discovered from every page
• ITCSS/BEM Sass architecture organized through layer directories and imported from assets/css/main.scss
• GitHub Actions deployment ready for plugins not supported by the native GitHub Pages builder

Requirements

These tools are needed to run and customize Eyvan locally, verify changes, and publish the repository; GitHub Actions installs its own build dependencies for hosted deployments.

• Ruby and Bundler
• Jekyll-compatible Ruby environment
• Git, if cloning or publishing the repository

Contributor QA also uses Node.js and npm for Playwright and axe-core checks. CI runs those tools on the Node.js version in .nvmrc; use npm ci before running the local QA scripts. Previewing search locally also needs npm ci.

Install dependencies with Bundler before running the site:

bundle install

Quick Start

Use these steps to run the shipped template locally for development and customization. For publishing with GitHub Pages, see Deployment.

1. Clone the repository or create a new repository from this template.

   git clone https://github.com/amirhs1/eyvan.git
   cd eyvan
   

2. Install dependencies.

   bundle install
   

3. Run the site locally.

   bundle exec jekyll serve
   

4. Open the local site.

   http://localhost:4000/eyvan/
   

This is the beginning of the README. Read the rest at the original. Read the full README ↗