Documentation — Nairobilens

Welcome to the Nairobilens Documentation. This guide covers setup, installation, customization, content management, and deployment.

Setup and Installation

Nairobilens is an Astro template designed for News and Magazine websites. Follow the steps below to get your local environment running.

Step 1: Prepare Your Tools

Ensure you have the following installed:

Node.js — Download from nodejs.org (includes npm). Verify with node -v.
npm — Installed with Node.js. Verify with npm -v.
Visual Studio Code — Recommended editor at code.visualstudio.com.

Step 2: Clone and Open the Project

Download and unzip the project folder.
Open the folder in VS Code or your preferred editor.
Open a terminal (Terminal > New Terminal) and navigate to the project root.

Step 3: Install Dependencies and Run

npm install
npm run dev
npm run build

Open http://localhost:4321 to preview the portal.
npm run build generates optimized production files in the dist/ folder, ready for deployment.

Project Folder Structure

src/
 ├── components/     # Reusable UI components
 ├── content/        # MDX content (blog, page, etc.)
 │   ├── blog/       # Article MDX files
 │   └── page/       # Static pages (docs, privacy, terms, etc.)
 ├── data/           # Author registry (authors.ts)
 ├── layouts/        # Layout components (MainLayout, etc.)
 ├── pages/          # Astro route files
 └── styles/         # Global styles and Tailwind config

Customization

Brand Colors & Fonts

Edit src/styles/style.css to change the primary color, fonts, and other global tokens:

@import "tailwindcss";
@theme {
  --color-brand:      oklch(51.1% 0.262 276.966);
  --color-brand-dark: oklch(45.7% 0.24 277.023);
  --color-accent:     oklch(68.1% 0.162 75.834);
  --color-dark:       oklch(37.1% 0 0);
  --color-muted:      oklch(55.6% 0 0);
  --color-light:      oklch(92.2% 0 0);

  --font-heading: 'Roboto', serif;
  --font-body:    'Inter', sans-serif;
}

Tailwind Utility Classes

Modify Tailwind classes directly in .astro files inside /src. Refer to the Tailwind CSS docs for available utilities.

Navigating the Site

Page	URL	Description
Home	`/`	Featured stories, trending, and latest articles
Category	`/{category}`	Browse articles by topic
Category Page 2+	`/{category}/2`	Paginated category listing
Tag	`/tag/{tag}`	Articles grouped by keyword
Tag Page 2+	`/tag/{tag}/2`	Paginated tag listing
Author	`/author/{id}`	Writer profile and article archive
Search	`/search?q=query`	Full-text search across all articles
Static Pages	`/page/{slug}`	Docs, privacy, terms, etc.

Content Categories

Category	URL
News	`/news`
Sports	`/sports`
Others	`/others`

MDX Frontmatter Format

Articles are written in MDX and placed in src/content/blog/. The required frontmatter fields are:

---
title: "Your Article Title"
cover: "/img/your-cover.jpg"
date: "2025-06-01"
category: "technology"
tags:
  - Tag1
  - Tag2
readTime: 7
featured: false
authorId: "your-author-id"
excerpt: |
  A brief 1–2 sentence description of your article.
---

Field	Type	Required	Notes
`title`	string	✅	Article headline
`cover`	string	✅	Path to cover image in `/public/img/`
`date`	string	✅	Format: `YYYY-MM-DD`
`category`	string	✅	Lowercase, matches existing categories
`tags`	array	✅	Array of tag strings
`readTime`	number	✅	Estimated read time in minutes
`featured`	boolean	✅	`true` to highlight in featured sections
`authorId`	string	✅	Must match an `id` in `authors.ts`
`excerpt`	string	✅	Short description for cards and SEO

Author Profiles

Author data is centrally managed in src/data/authors.ts. Each author has a unique id in kebab-case that is referenced in article frontmatter via authorId.

"james-carter": {
  id: "james-carter",
  name: "James Carter",
  job: "Senior Sports & Technology Correspondent",
  avatar: "/img/male1.jpg",
  verified: true,
  description: "...",
  socials: {
    twitter: "#",
    linkedin: "#",
    email: "james@nairobilens.com",
  },
}

To register as a new author, add an entry to authors.ts following the same structure.

Adding New Pages

Create .mdx files in src/content/page/ for content-driven static pages. The frontmatter schema:

---
title: "Page Title"
subtitle: "Optional subtitle"
badge: "Label"
badgeIcon: "bi:lightning-fill"
cover: "/img/cover.jpg"
lastUpdated: "2025-06-01"
---

Pages are automatically rendered at /page/{slug} based on the filename.

Search

Nairobilens uses client-side full-text search powered by Alpine.js. The search index includes:

Article titles
Excerpts
Categories and tags
Author names

Access search at /search or use direct queries:

/search?q=artificial+intelligence
/search?q=climate
/search?q=James+Carter

Deployment

Platform	Notes
Vercel	Seamless Astro integration — vercel.com
Netlify	Continuous deployment + edge functions — netlify.com
Custom Server	Upload `dist/` via FTP, SSH, or CI/CD

Best Practices

Keep components small and reusable for easier maintenance.
Always set SEO title and description in your layout for discoverability.
Use descriptive authorId values matching entries in authors.ts.
Keep cover images consistently sized (recommended: 1200×630px).
Use lowercase category names in frontmatter to match URL routes.

Support

Found a bug or need help?

Technical support: techdasmin@gmail.com