https://github.com/landerox/zensical-theme-slate
A sleek, developer-focused, and open-source bilingual (EN/ES) personal portfolio and blog template built with Zensical.
https://github.com/landerox/zensical-theme-slate
bilingual developer-portfolio markdown slate static-site-generator theme zensical zensical-theme
Last synced: about 2 months ago
JSON representation
A sleek, developer-focused, and open-source bilingual (EN/ES) personal portfolio and blog template built with Zensical.
- Host: GitHub
- URL: https://github.com/landerox/zensical-theme-slate
- Owner: landerox
- License: mit
- Created: 2026-06-07T15:22:01.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-07T17:04:30.000Z (about 2 months ago)
- Last Synced: 2026-06-07T18:15:35.043Z (about 2 months ago)
- Topics: bilingual, developer-portfolio, markdown, slate, static-site-generator, theme, zensical, zensical-theme
- Language: CSS
- Homepage: https://landerox.com/zensical-theme-slate
- Size: 259 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
This repository is a hybrid **Packaged Theme + Starter Template** built on top of the modern, Rust-powered [Zensical](https://zensical.org) static site generator. It provides a highly interactive developer portfolio theme (`zensical-theme-slate`) and a pre-configured starter layout so you can customize and launch your site in minutes.
Designed for developers, technical writers, and creators who want a stunning, high-performance bilingual portfolio and blog site with robust, production-grade quality controls and automated CI/CD out of the box.
---
## 🌟 Key Features
* **Sleek Slate Aesthetics**: Deep graphite base (`#0b0f19`) and tailored indigo/slate accents for a modern, polished developer aesthetic.
* **Interactive Neural Background**: Canvas particle system connecting nodes with lines that respond smoothly to mouse movements.
* **circular Page Ripple**: A gorgeous ripple transition triggered when toggling light/dark modes (fully respects `prefers-reduced-motion`).
* **3D Glare Tilt Cards**: Project and experience cards that tilt dynamically in response to mouse coordinates with a glassmorphism reflection overlay.
* **Complete Bilingual Support (EN/ES)**: Built-in layout for English at `/` and Spanish at `/es/` with full relative path and structure symmetry.
* **Automated CI/CD Workflows**: Hand-crafted GitHub Actions for deploying compiles to GitHub Pages, link validation, and automated dependency upgrades.
* **Elite Security & Quality Standards**: Pre-configured pre-commit hooks for markdown lints, spellchecking (`cspell`), secrets detection (`gitleaks`), dependency auditing (`pip-audit`), and GitHub action security (`zizmor`).
---
## 🚀 Quick Start
You can get your site up and running in minutes using one of the following options:
### Option 1: Dev Container (Recommended)
This repository includes a fully configured **Dev Container** (VS Code / GitHub Codespaces) with Python 3.13, `uv`, `just`, and all linter binaries pre-installed.
1. Click the green **"Use this template"** button to create your clone on GitHub.
2. Open your new repository in VS Code.
3. Click the notification **"Reopen in Container"** (or press `F1`, type `Dev Containers: Reopen in Container`).
4. Once loaded, open a terminal inside VS Code and run:
```bash
just serve
```
5. Open [http://localhost:8000](http://localhost:8000) to see your website!
### Option 2: Local Manual Setup
If you prefer to install dependencies directly on your host machine:
**Prerequisites:**
* Python 3.13+
* [`uv`](https://docs.astral.sh/uv/) (Python package manager)
* [`just`](https://github.com/casey/just) (command runner)
**Setup:**
```bash
# 1. Install all dependencies and setup the virtual environment
just sync
# 2. Install pre-commit quality hooks
just hooks-install
# 3. Start the English development server (port 8000)
just serve
# 4. Start the Spanish development server (port 8001)
just serve-es
```
### Option 3: Use as a Reusable Theme on an Existing Project
If you already have an existing Zensical site and simply want to apply the **Slate Theme**:
1. **Install the package** from PyPI:
Using `uv`:
```bash
uv add zensical-theme-slate
```
Using `pip`:
```bash
pip install zensical-theme-slate
```
*Alternatively, you can install the latest development version directly from GitHub:*
```bash
pip install git+https://github.com/landerox/zensical-theme-slate.git
```
2. **Configure your site** to load the theme inside your `zensical.toml`:
```toml
[project.theme]
name = "slate"
```
> [!NOTE]
> **Zero-Configuration Asset Injection:** You do NOT need to declare `extra_css` or `extra_javascript` in your `zensical.toml` to load the Slate theme's stylesheets and scripts. The theme uses built-in layout inheritance (`main.html`) to inject them automatically.
---
## 📦 Repository Structure
The project is architected as a hybrid repository to give you the benefits of a packaged, reusable theme alongside a clean, local starter workspace:
* **`zensical_theme_slate/`**: The core, reusable Python theme package containing the slate design assets (`extra.css`, `extra.js`), default graphics (logos, profile, banner, screenshot), layout template overrides (`main.html`), and theme configurations (`mkdocs_theme.yml`).
* **`content/`**: Your website's content source directory.
* `content/en/`: English Markdown pages and blog posts.
* `content/en/assets/`: Optional directory where you can place custom overrides (e.g., your own profile picture, logo, or custom stylesheets).
* `content/es/`: Spanish Markdown pages and blog posts.
* **`zensical.toml` / `zensical.es.toml`**: The site settings for English and Spanish builds, both referencing the packaged `"slate"` theme.
* **`Justfile`**: Simple commands to run your dev server, linting suite, and site compilation.
---
## 🛠️ Customization Guide
Personalizing the site is straightforward:
1. **Global Site Config**: Open `zensical.toml` (English) and `zensical.es.toml` (Spanish) to update the site title, description, social links, and author details.
2. **Generic Placeholders**: We've pre-loaded home pages (`content/en/index.md` and `content/es/index.md`) with braces-style placeholders like `{Your Name}` or `{Your Specialty}`. Swap these out for your real info.
* *Note: Avoid plain square brackets like `[Placeholder]` without a link, as Zensical interprets them as unresolved markdown link references. Use curly braces `{Placeholder}` instead.*
3. **Bilingual & Custom Assets (DRY)**: The core theme styles, scripts, and default graphics reside within the packaged theme directory (`zensical_theme_slate/assets/`). If you want to customize your site's graphics, stylesheet tweaks, or scripts:
* Place your custom overrides inside `content/en/assets/` (e.g., your own profile picture at `content/en/assets/images/profile.svg` or custom stylesheets). They will automatically take precedence over the packaged theme defaults.
* Never edit files in `content/es/assets/` directly! During development or builds, `just sync-assets` automatically synchronizes your English asset overrides to the Spanish assets folder.
4. **Content Symmetry**: Every page or blog post under `content/en/` must have a relative-path counterpart under `content/es/`. Run the bilinguality validator to verify alignment:
```bash
python3 scripts/check_i18n.py
```
---
## 🌍 Automated Deployment
We have included a pre-configured GitHub Actions deployment workflow (`.github/workflows/deploy.yml`) to compile and publish your site automatically.
1. Go to your repository settings on GitHub: **Settings** -> **Pages**.
2. Under **Build and deployment** -> **Source**, select **GitHub Actions**.
3. Push your changes to the `main` branch, and the site will build and deploy to GitHub Pages instantly!
---
## 👥 Contributing
While this repository serves as a starter template and packaged theme, technical corrections, bug reports, or suggestions are highly appreciated. Please refer to the [Contributing Guidelines](.github/CONTRIBUTING.md) before opening an Issue or submitting a Pull Request.
---
## 📄 License
To maintain a clear boundary between the open-source engine and the theme's core assets or template content, this repository operates under a dual-license model:
* **Source Code** (`pyproject.toml`, `.github/`, scripts, tooling configurations) is released under the [MIT License](LICENSE).
* **Starter Template Content** (Markdown files under `content/`, default demo images, and placeholder prose) is released under the [Creative Commons Attribution 4.0 International License (CC-BY-4.0)](LICENSE-CONTENT).