WebNami Documentation

WebNami is a simple yet powerful blogging tool built specifically for developers. It uses 11ty (Eleventy) under the hood to generate fast, static websites that load instantly and rank well in search engines.

Unlike complex content management systems, WebNami focuses on what developers care about most:

• Fast performance
• Clean code
• SEO optimization
• Minimal setup
• Easy customization

You write your blog posts in Markdown, and WebNami handles everything else - from generating optimized HTML to creating sitemaps and RSS feeds.

Performance First

• Lightning fast loading: Built with 11ty for optimal performance
• Perfect scores: Achieves 100/100 on all Core Web Vitals metrics
• Minimal footprint: Clean HTML with minimal JavaScript

SEO Built-in

• SEO audit tool: Built-in command to check your site for SEO issues
• Complete meta tags: Automatic title, description, and Open Graph tags
• Structured data: Rich snippets for better search visibility
• XML sitemap: Auto-generated for search engines
• RSS feed: Automatic syndication support
• Canonical URLs: Prevents duplicate content issues

Developer Experience

• Markdown writing: Write posts in familiar Markdown format
• Multiple layouts: 6 built-in layout options
• Syntax highlighting: Code blocks look great out of the box
• Hot reload: Instant preview during development
• Clean structure: Organized project files

Design & Usability

• Responsive design: Looks great on all devices
• Dark/Light mode: Automatic theme switching
• Clean interface: Minimal, distraction-free design
• Custom 404 page: Better user experience for broken links

Before installing WebNami, make sure you have:

• Node.js: Version 20 or higher
• npm: Version 10 or higher (comes with Node.js)

Checking Your Versions

node --version
npm --version

If you need to update Node.js, download it from nodejs.org.

WebNami offers two easy installation methods:

Method 1: Using npx (Recommended)

This is the fastest way to get started:

npx create-webnami-blog my-blog-name
cd my-blog-name

Method 2: Using npm

npm create webnami-blog my-blog-name
cd my-blog-name

Both methods will:

1. Create a new directory with your blog name
2. Download all necessary files
3. Install dependencies automatically
4. Set up the basic project structure

Once installation is complete, follow these steps:

1. Navigate to Your Project

cd my-blog-name

2. Configure Your Site

Edit the config.js file to customize your site:

// config.js
module.exports = {
  site: {
    name: "My Developer Blog",
    url: "https://myblog.com",
    language: "en",
  },
  homepage: {
    heading: "Welcome to My Blog",
    metadata: {
      title: "My Developer Blog",
      description: "Thoughts on code, tech, and development",
    },
  },
};

3. Add Your Logo and Favicon

• Place your logo in the images/ directory
• Update the logo path in config.js
• Add a favicon to the images/ directory

4. Start Development Server

npm run dev

Visit http://localhost:8080 to see your blog in action!

5. Create Your First Post

npm run post "My First Blog Post"

This creates a new Markdown file in the posts/ directory with the correct structure.

Understanding WebNami's file organization helps you work more efficiently:

my-blog-name/
├── config.js              # Main site configuration
├── package.json           # Project dependencies
├── custom.css             # Your custom styles
├── images/                # Logo, favicon, and images
├── pages/                 # Static pages (only about.md)
│   └── about.md
├── posts/                 # Your blog posts (Markdown files)
│   ├── my-first-post.md
│   └── another-post.md
├── src/                   # System files (don't edit these)
└── _site/                 # Built website (generated automatically)

Important Directories

You should edit these:

• config.js - Site settings
• custom.css - Your styles
• images/ - Your assets
• pages/about.md - About page
• posts/ - Your blog posts

Don't edit these:

• src/ - System files
• _site/ - Generated output

The config.js file controls all aspects of your site. Here's a detailed breakdown:

Basic Site Information

site: {
  name: "Your Site Name",           // Appears in header and meta tags
  url: "https://yoursite.com",      // Your site's URL
  language: "en",                   // Language code for HTML
  logo: "/images/logo.svg",         // Path to your logo
  favicon: "/images/favicon.ico",   // Path to your favicon
  csp: "default-src 'self'"         // Content Security Policy
}

Layout Options

Choose from 6 different homepage layouts:

layout: "triofeatured";

• trio: Three-column grid of posts
• triofeatured: Three columns with featured post
• mono: Single column layout
• duo: Two-column layout
• monofeatured: Single column with featured post
• duofeatured: Two columns with featured post

Homepage Settings

homepage: {
 heading: "Welcome to My Blog", // Main headline shown on homepage hero section
 metadata: {
   title: "My Blog - Developer Thoughts", // Browser tab title and search engine title (30-60 chars)
   description: "A blog about web development and programming", // Meta description for SEO and social previews (140-155 chars)
   img: "/images/social-image.png"  // Social sharing image for Facebook, Twitter, LinkedIn previews (1200x630px recommended)
 }
}

Navigation Menu

navbar: {
  links: [
    { name: "About", href: "/about/" }, // Internal link - text shown in menu and destination URL
    { name: "Link", href: "https://example.com" }, // External link
  ];
}

Footer Configuration

footer: {
  // Displays as clickable social media icons
  socialLinks: [
    { name: "instagram", href: "https://instagram.com/yourusername" },
    { name: "gitHub", href: "https://github.com/yourusername" },
    { name: "twitter", href: "https://twitter.com/yourusername" }
  ],
  linkGroups: [
    {
      title: "Resources", // Section heading in footer (optional)
      links: [
        { name: "Documentation", href: "/docs/" }, // Footer link - internal or external URLs supported
        { name: "API", href: "/api/" } // Grouped under the title above
      ]
    }
  ]
}

Posts Per Page

postsPerPage: 10; // Number of posts shown on listing pages

Writing Blog Posts

Creating a New Post

Always use the built-in command to create posts:

npm run post "Your Post Title"

This creates a file like posts/your-post-title.md with the correct structure:

---
layout: "layouts/post"
title: "Your Post Title"
tags: []
category: ""
author: ""
date: 2024-01-15
---

Your post content goes here...

Post Frontmatter Fields

Required fields:

• layout: The template file used to render this page
• title: The post title
• date: Publication date (YYYY-MM-DD format) - created automatically

Optional fields:

• tags: Array of tags ["javascript", "web-development"]
• category: Single category name "tutorials"
• author: Author name "John Doe"

Writing Content

Write your post content in Markdown below the frontmatter:

---
title: "Getting Started with JavaScript"
tags: ["javascript", "beginners"]
category: "tutorials"
author: "Jane Developer"
date: 2024-01-15
---

JavaScript is a powerful programming language...

## Code Examples

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

## Lists

- First item
- Second item
- Third item

**Bold text** and _italic text_ work as expected.

Creating the About Page

Edit pages/about.md to customize your about page:

---
layout: "layouts/page"
eleventyComputed:
  title: "About Us - Learn More About "
  description: "About Us - Learn More About "
  img: ""
permalink: "/about/"
---

# About Me

I'm a developer passionate about creating fast, accessible websites...

Important: Only about.md is supported in the pages directory. Don't add other files here.

Styling with custom.css

All visual customization happens in the custom.css file at the project root. WebNami provides CSS custom properties (variables) you can override:

/* Color palette - edit these values */
:root[data-theme="light"] {
  /* Light theme colors */
  --color-primary: #155dfc;
  --color-background: #ffffff;
  --color-content: #364153;
  --color-accent: #6a7282;
  --color-footer: #f3f4f6;
}

:root[data-theme="dark"] {
  /* Dark theme colors */
  --color-primary: #155dfc;
  --color-background: #121212;
  --color-content: #faf9f6;
  --color-accent: #ffffff;
  --color-footer: #000000;
}

Development Commands

Start Development Server

npm run dev

• Starts local server at http://localhost:8080
• Enables hot reload (automatic refresh when files change)
• Shows build errors in the terminal

Create New Post

npm run post "Your Post Title"

• Generates a new Markdown file with correct frontmatter
• Uses current date automatically
• Converts title to URL-friendly filename

Production Commands

Build for Production

npm run build

• Generates optimized static site in _site/ directory
• Minifies CSS and JavaScript
• Optimizes images
• Creates sitemap and RSS feed

SEO Analysis

npm run seo

• Scans all HTML files for SEO issues
• Checks meta tags, headings, and content structure
• Provides actionable recommendations
• Shows warnings and errors in terminal

Example SEO Output

📄 _site\this-is-the-latest-post\index.html
------------------------------------------------------------
   ✅ H1 Tag: Found 1 H1 tag
   ❌ Title Length: Title too short (23 chars). Should be 30-60 characters.
   ✅ Word Count: Word count is good (376 words)
   ✅ Meta Description: Meta description length is optimal (147 chars)
   ✅ Image Alt Text: All 4 images have proper alt text
   ✅ H2 Structure: Found 5 H2 tag(s) for good content structure
   ✅ Duplicate H2s: No duplicate H2 tags found
   ✅ Open Graph: All essential Open Graph tags present
   ✅ Canonical URL: Canonical URL found: http://example.com/this-is-the-latest-post/

   📊 Summary: 8 passed, 1 failed, 0 info

Deployment

WebNami generates static files that can be hosted anywhere. Here are popular options:

Netlify

1. Connect your GitHub repository to Netlify
2. Set build command: npm run build
3. Set publish directory: _site
4. Deploy automatically on every commit

Vercel

1. Connect your GitHub repository to Vercel
2. Vercel automatically detects the build settings
3. Deploy with zero configuration

GitHub Pages

1. Build your site: npm run build
2. Push the _site contents to gh-pages branch
3. Enable GitHub Pages in repository settings

Traditional Web Host

1. Run npm run build locally
2. Upload the contents of _site/ directory
3. Point your domain to the uploaded files

Common Issues

Port 8080 Already in Use

The development server will automatically try other ports (8081, 8082, etc.). Check the terminal output for the correct URL.

Images Not Loading

• Ensure images are in the images/ directory
• Use relative paths: /images/my-image.jpg
• Check file names for typos

Posts Not Appearing

• Check the date in frontmatter (future dates won't show)
• Ensure the file is in the posts/ directory
• Verify frontmatter syntax (proper YAML format)

Getting Help

If you encounter issues:

1. Check the terminal for error messages
2. Restart the development server (Ctrl+C, then npm run dev)
3. Clear browser cache and refresh
4. Check file syntax for typos in frontmatter or config
5. Search existing issues on GitHub
6. Create a new issue with details about your problem

Getting Help

• Email: [email protected]
• GitHub Issues: Report bugs or request features
• Documentation: Check this guide for answers

Contributing

WebNami is open source! We welcome:

• Bug reports
• Feature requests
• Code contributions
• Documentation improvements

Community

• Star the project on GitHub
• Share your WebNami sites
• Help other users in discussions

Now that you know how to use WebNami, here are some ideas:

1. Write your first few blog posts about your projects
2. Set up automatic deployment with Netlify or Vercel
3. Share your blog with the developer community

WebNami gives you everything you need to start blogging without the complexity. Focus on writing great content, and let WebNami handle the technical details.

Happy blogging! 🚀