Novash

Novash is an open-source, command-line SEO checker for websites. Point it at a URL and it downloads the page, audits the core on-page SEO elements, scores the result out of 100, and tells you exactly what to fix — all from your terminal.

---

Features

• 🔍 Automated page crawling — fetches and parses any public webpage, with built-in handling for timeouts, bad URLs, and connection errors.
• 📄 Title check — detects whether the page has a non-empty <title> tag.
• 📝 Meta description check — detects a non-empty <meta name="description"> tag.
• 📌 H1 check — finds meaningful <h1> tags, automatically ignoring ones that are hidden (display:none, aria-hidden, etc.), empty, or too short to be a real heading.
• 🖼️ Image alt-text audit — counts every <img> tag and reports how many are missing alt text.
• 📊 SEO scoring — a 100-point score with clear, transparent deductions (see Scoring below).
• 💡 Actionable suggestions — plain-language fixes generated from whatever the audit finds wrong.
• 📤 JSON export — save the full report to a file for use in other tools, dashboards, or CI pipelines.
• 🎨 Colorful terminal output — powered by Rich, with green/yellow/red color-coding so you can scan a report at a glance.

---

Installation

Novash requires Python 3.8+.

Clone the repository and install it locally:

git clone https://github.com/<your-username>/novash.git
cd novash
pip install .

This installs Novash's dependencies (requests, beautifulsoup4, rich, typer) and registers the novash command on your PATH.

For development (editable install, so code changes take effect immediately):

pip install -e .

---

Usage Examples

Scan a website and print the report to your terminal:

novash scan https://example.com

Scan a website and also save the full report as JSON:

novash scan https://example.com --export report.json

View help for any command:

novash --help
novash scan --help

---

CLI Commands

Command	Description
novash scan <url>	Crawl a URL, run all SEO checks, calculate the score, and print the report.
novash scan <url> --export <file>	Same as above, and also save the full report as a pretty-printed JSON file.
novash --help	Show general help and available commands.
novash scan --help	Show detailed help for the scan command.

Options

Option	Description
--export <filename>	Save the report as JSON, e.g. --export report.json. Optional.

---

Example Output

╭───────────────────╮
│ NOVASH SEO REPORT │
╰───────────────────╯
🌐 Website: https://example.com

📄 Title
✓ Title found:
  Example Domain

📝 Meta Description
✗ Meta description missing

📌 H1 Tags
✓ H1 tags found:
  - Example Domain

🖼️  Images
✓ Total images: 11
✓ Images with alt text: 1
✗ Images without alt text: 10

╭──────────────────────╮
│ ⚠️ SEO Score: 82/100 │
╰──────────────────────╯

💡 Suggestions
- Add a meta description.
- Add alt text to 10 images.

If every check passes, the Suggestions section shows a single line instead:

💡 Suggestions
✅ No SEO issues found.

Scoring

Novash starts every page at 100 points and deducts:

• 15 points if the title is missing
• 15 points if the meta description is missing
• 15 points if no meaningful H1 tag is found
• Up to 20 points, proportional to the percentage of images missing alt text: penalty = (images_without_alt / total_images) * 20

The score never drops below 0, and is color-coded in the terminal:

Score	Color
90–100	🟢 Green
70–89	🟡 Yellow
0–69	🔴 Red

---

Roadmap

Planned improvements for future versions:

• Multi-page / full-site crawling (follow internal links)
• Additional checks: canonical tags, robots meta, Open Graph tags, heading hierarchy (H1–H6), broken links, page load time
• HTML and PDF report export, alongside JSON
• Configurable scoring weights via a config file
• Batch scanning of multiple URLs from a file
• CI/CD integration (fail a build if the score drops below a threshold)
• Publish to PyPI for pip install novash

Have an idea? Open an issue — see Contributing below.

---

Contributing

Contributions are welcome! To get started:

1. Fork the repository and clone your fork.
2. Create a new branch for your change:

   git checkout -b feature/your-feature-name
   

3. Install in editable mode so your changes are picked up immediately:

   pip install -e .
   

4. Make your changes, and keep functions small, documented, and covered by a quick manual test (each module includes a if __name__ == "__main__": block you can run directly, e.g. python checks.py).
5. Commit and push your branch, then open a pull request describing what you changed and why.

Please keep pull requests focused — one feature or fix per PR makes review much easier. Bug reports and feature requests are just as welcome as code; feel free to open an issue.

---

License

This project is open-source. Add your preferred license (e.g. MIT) in a LICENSE file before publishing.