Skip to content

Commit 3e7b454

Browse files
tobiutobiu
committed
#7446 tickets as md files
1 parent f6a233f commit 3e7b454

8 files changed

Lines changed: 182 additions & 19 deletions

‎.github/ISSUE/epic-enhance-neo-website-seo.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Epic: Enhance SEO for Neo.mjs Website
2+
3+
GH ticket id: #7446
4+
5+
**Assignee:** tobiu
6+
**Status:** To Do
7+
8+
## Scope
9+
10+
This epic aims to improve the search engine optimization (SEO) of the Neo.mjs website, specifically focusing on making the blog and learning content discoverable by search engines and Large Language Models (LLMs). The goal is to increase organic traffic and improve the visibility of the Neo.mjs framework.
11+
12+
## Top-Level Items & Implementation Phases
13+
14+
### Phase 1: LLM & Sitemap Integration
15+
16+
- **Goal:** Implement `LLM.txt` and a sitemap to enhance content discoverability for search engines and LLMs.
17+
18+
## Strategic Overview
19+
20+
Our strategy to enhance SEO is a two-pronged approach that addresses both the initial server response and the client-side navigation within our Single-Page Application (SPA), all while working within the constraints of a static hosting environment like GitHub Pages.
21+
22+
### 1. Fixing the Root Domain (`neomjs.com`)
23+
24+
The most critical issue is that our root domain serves a meta-refresh redirect, offering no content to search engines. We will fix this by modifying our deployment process to serve a real, content-rich `index.html` at the root.
25+
26+
- **The `<base>` Tag Solution:** The deployment script will copy the portal app's `index.html` to the root and inject a `<base href="/dist/production/apps/portal/">` tag into its head. This ensures that crawlers see real content immediately, while all relative asset paths for our live IDE continue to function correctly.
27+
28+
### 2. Managing SPA Routes (Client-Side)
29+
30+
Once the app is loaded, we need to handle client-side route changes to prevent duplicate content issues and provide accurate metadata for each page.
31+
32+
- **The `HeadManager` Addon:** We will build a new main thread addon responsible for dynamically manipulating the document's `<head>`. Its primary job will be to set the `canonical URL` for each route, which is essential for telling search engines the "true" address of a page and consolidating our SEO authority. It will also manage titles and other meta tags.
33+
34+
### 3. Automating Content Discovery
35+
36+
To ensure search engines have an up-to-date map of our site, we will automate the generation of discovery files.
37+
38+
- **Generator Script:** A new build script will parse our content manifests (like `learn/tree.json`) to automatically generate a complete `sitemap.xml` and `llm.txt`. This ensures these files are never out of date and requires zero manual maintenance.
39+
40+
This combination of a server-side deployment fix and a client-side management addon, supported by automated file generation, provides a robust and sustainable solution to dramatically improve the project's visibility.
41+
42+
## Sub-Tasks
43+
44+
### Phase 1: Foundational Tooling
45+
46+
- **To Do:** ticket-fix-root-domain-seo-with-base-href.md
47+
- **To Do:** ticket-create-head-manager-addon.md
48+
- **To Do:** ticket-create-sitemap-generator-script.md
49+
- **To Do:** ticket-generate-sitemap-file.md
50+
- **To Do:** ticket-generate-llm-txt-file.md
51+
- **To Do:** ticket-create-update-robots-txt-for-seo.md

‎.github/ISSUE/ticket-create-head-manager-addon.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Ticket: Create HeadManager Addon with Canonical URL Support
2+
3+
GH ticket id: #7448
4+
5+
**Assignee:** tobiu
6+
**Status:** To Do
7+
8+
**Parent Epic:** epic-enhance-neo-website-seo.md
9+
10+
## Description
11+
12+
To solve the critical duplicate content issue caused by the SPA architecture and multiple deployment environments (dev, prod, esm), a main thread addon is required to dynamically manage the document's `<head>`.
13+
14+
This is the highest priority task for the SEO epic, as it enables crawlers like Google to correctly index our content by providing a canonical URL.
15+
16+
## Acceptance Criteria
17+
18+
1. Create a new main thread addon at `src/main/addon/HeadManager.mjs`.
19+
2. The addon must expose the following RMA methods:
20+
- `setTitle(newTitle)`: Updates the content of the `<title>` tag.
21+
- `setTag(tagObject)`: A smart method that creates or updates a `<meta>` or `<link>` tag. It should remove any existing tag with the same `name` or `property` before adding the new one.
22+
- `setCanonical(url)`: A dedicated method that creates or updates the `<link rel="canonical" href="...">` tag.
23+
3. The `portal` application controller (`apps/portal/view/ViewportController.mjs`) must be updated to:
24+
- Listen for route changes.
25+
- On route change, call the `HeadManager` addon's methods to update the title, meta description, and, most importantly, the canonical URL for the new route.

‎.github/ISSUE/ticket-create-llm-txt-for-ai-content-understanding.md‎

Lines changed: 0 additions & 19 deletions
This file was deleted.

‎.github/ISSUE/ticket-create-sitemap-generator-script.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Ticket: Create Sitemap & LLM.txt Generator Script
2+
3+
GH ticket id: #7449
4+
5+
**Assignee:** tobiu
6+
**Status:** To Do
7+
8+
**Parent Epic:** epic-enhance-neo-website-seo.md
9+
10+
## Description
11+
12+
To ensure our SEO files (`sitemap.xml`, `llm.txt`) are always up-to-date with the site's content, we need to automate their generation. Manually maintaining these files is not sustainable.
13+
14+
This task is to create a new build script responsible for parsing our content manifests and generating the necessary data for these SEO files.
15+
16+
## Acceptance Criteria
17+
18+
1. Create a new build script at `buildScripts/generate-seo-files.mjs`.
19+
2. The script must read and parse `learn/tree.json` to extract all content routes.
20+
3. It should also be able to scan the `learn/blog` directory to find any blog posts that may not be in the `tree.json` file.
21+
4. The script should compile a comprehensive list of all valid content URLs.
22+
5. It should expose methods that can be used by other functions to get this URL list in different formats (e.g., as a simple array, or formatted for XML or `llm.txt`).

‎.github/ISSUE/ticket-create-update-robots-txt-for-seo.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Ticket: Update robots.txt for SEO
2+
3+
GH ticket id: #7453
4+
5+
**Assignee:** tobiu
6+
**Status:** To Do
7+
8+
**Parent Epic:** epic-enhance-neo-website-seo.md
9+
**Depends On:** ticket-generate-sitemap-file.md
10+
11+
## Description
12+
13+
The `robots.txt` file gives instructions to web crawlers about which pages they can or cannot crawl. It should also point to the location of our sitemap.
14+
15+
## Acceptance Criteria
16+
17+
1. Create or update the `robots.txt` file in the `apps/portal/` directory.
18+
2. Ensure the file includes a `Sitemap:` directive pointing to the absolute URL of the `sitemap.xml` file (e.g., `Sitemap: https://neomjs.com/sitemap.xml`).
19+
3. Optionally, this process can be automated as part of the `generate-seo-files.mjs` build script.

‎.github/ISSUE/ticket-fix-root-domain-seo-with-base-href.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Ticket: Fix Root Domain SEO with Base-Href-Patched Index
2+
3+
GH ticket id: #7447
4+
5+
**Assignee:** tobiu
6+
**Status:** To Do
7+
8+
**Parent Epic:** epic-enhance-neo-website-seo.md
9+
10+
## Description
11+
12+
The project's root domain (`neomjs.com`) currently uses a meta refresh, which is detrimental to SEO as it provides no content for crawlers at the most important URL.
13+
14+
To fix this within the constraints of GitHub Pages hosting and the need to preserve the repository's file structure for the live IDE, we will modify the deployment process.
15+
16+
## Acceptance Criteria
17+
18+
1. The build/deployment script needs to be modified.
19+
2. Instead of creating a redirect file, the script must **copy** the production portal app's `index.html` (`/dist/production/apps/portal/index.html`) to the repository root (`/index.html`).
20+
3. The script must then **inject a `<base>` tag** into the `<head>` of this new root `index.html` file.
21+
- The tag should be: `<base href="/dist/production/apps/portal/">`
22+
4. The outcome should be tested thoroughly to ensure:
23+
- Visiting `neomjs.com` directly serves the portal app.
24+
- All application assets (JS, CSS, workers) load correctly.
25+
- Other top-level paths (e.g., `/apps/covid/`, `/examples/`) remain accessible and functional.

‎.github/ISSUE/ticket-generate-llm-txt-file.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Ticket: Generate LLM.txt File via Build Script
2+
3+
GH ticket id: #7452
4+
5+
**Assignee:** tobiu
6+
**Status:** To Do
7+
8+
**Parent Epic:** epic-enhance-neo-website-seo.md
9+
**Depends On:** ticket-create-sitemap-generator-script.md
10+
11+
## Description
12+
13+
To improve the ability of Large Language Models (LLMs) to understand our content, an `llm.txt` file is needed. This file will be automatically generated by a build script to ensure it stays in sync with our content.
14+
15+
## Acceptance Criteria
16+
17+
1. Enhance the `buildScripts/generate-seo-files.mjs` script.
18+
2. Add a function to the script that takes the parsed list of content URLs and formats them into the `llm.txt` syntax (`Allow: /path/to/page`).
19+
3. The script should write the final output to a new `llm.txt` file in the `apps/portal/` directory.
20+

‎.github/ISSUE/ticket-generate-sitemap-file.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Ticket: Generate sitemap.xml File via Build Script
2+
3+
GH ticket id: #7451
4+
5+
**Assignee:** tobiu
6+
**Status:** To Do
7+
8+
**Parent Epic:** epic-enhance-neo-website-seo.md
9+
**Depends On:** ticket-create-sitemap-generator-script.md
10+
11+
## Description
12+
13+
A `sitemap.xml` file is essential for telling search engines which pages on our site are available for crawling. This file will be automatically generated by a build script to ensure it is always accurate.
14+
15+
## Acceptance Criteria
16+
17+
1. Enhance the `buildScripts/generate-seo-files.mjs` script.
18+
2. Add a function to the script that takes the parsed list of content URLs and formats them into the standard `sitemap.xml` format.
19+
3. The script should write the final XML output to a new `sitemap.xml` file in the `apps/portal/` directory.
20+
4. The task of submitting the sitemap to search consoles will be handled separately after generation is complete.

0 commit comments

Comments
 (0)