content-add-internal-links-to-article

name	content-add-internal-links-to-article
description	Analyze an article and add relevant internal links from both SLG and ITA projects. Use when the user asks to add internal or cross-project links to an article.
argument-hint	["path to article file"]

Add Internal Links to Article

Analyze an article, find relevant internal links from BOTH projects (SLG and ITA), and automatically insert them into the file.

Internal links include:

• Page links - links to standalone pages (e.g., /ru/mortgage/)
• Anchor links - links to sections within pages (e.g., #надежные-хесторы or /ru/mortgage/#документы)

Input

$ARGUMENTS

The input should be a path to an article file (e.g., _includes/ru/some-article.md).

Instructions

Phase 1: Setup

1. Read the article from the specified path

2. Determine article language from the path:

   • _includes/ru/ → Russian
   • _includes/ua/ → Ukrainian
   • _includes/en/ → English
   • _includes/es/ → Spanish

3. Understand link types:

   • Anchor links: point to a section on a page (e.g., #надежные-хесторы or /ru/mortgage/#документы-для-ипотеки)
   • Page links: point to standalone pages (e.g., /ru/mortgage/)
   • Internal links format: [text](#anchor), [text](/path/), or [text](/path/#anchor)
   • External links format: [text](https://site.com/path/){:target="_blank"} or [text](https://site.com/path/#anchor){:target="_blank"}

Phase 2: Internal Links (Current Project - SLG)

4. Load SLG links database:

   • _resources/internal_links_{lang}.json - contains all pages with anchors

5. Understand the internal_links_{lang}.json structure:

   {
     "pages": [
       {
         "path": "/",
         "url": "https://spainlifeguide.com/",
         "title": "Main page title",
         "description": "What this page is about",
         "anchors": ["anchor1", "anchor2"]
       },
       {
         "path": "/ru/mortgage/",
         "url": "https://spainlifeguide.com/ru/mortgage/",
         "title": "Ипотека в Испании",
         "description": "Complete mortgage guide",
         "anchors": ["документы-для-ипотеки", "пошаговая-инструкция-по-оформлению-ипотеки", ...]
       }
     ]
   }
   

   • Each page has a path, url, title, description, and list of anchors
   • Use path + anchor to create links like /ru/mortgage/#документы-для-ипотеки
   • For main page (path: "/"), just use #anchor

6. Analyze the article content for SLG-relevant topics:

   • Life in Spain topics: housing, healthcare, documents, legal matters, etc.
   • Look for mentions that correspond to existing SLG pages or anchors
   • Consider what additional reading would genuinely help the reader

7. Match terms to SLG pages and anchors:

   • Find phrases that relate to available pages or anchors
   • Use semantic matching based on page/anchor titles and descriptions
   • Can link to: page only (/ru/mortgage/), anchor on main page (#надежные-хесторы), or anchor on subpage (/ru/mortgage/#документы-для-ипотеки)

8. Apply conservative linking rules for internal links:

   • Max 3-5 internal links per article - quality over quantity
   • One link per term - link only the first meaningful occurrence
   • No redundant links - don't link terms already linked
   • No self-links - don't link to the current article/section
   • Prefer early mentions - link terms closer to the beginning
   • Context matters - only link when it genuinely helps the reader

9. Edit the file to add internal links

Phase 3: External Links (Sibling Project - ITA)

10. Load ITA links database from sibling project:

    • ../it-autonomos-spain/_resources/internal_links_{lang}.json - contains all pages with anchors

11. Understand the internal_links_{lang}.json structure:

    {
      "pages": [
        {
          "path": "/",
          "url": "https://itautonomos.com/",
          "title": "Main page title",
          "description": "What this page is about",
          "anchors": ["anchor1", "anchor2"]
        }
      ]
    }
    

    • Each page has a path, url, title, description, and list of anchors
    • Use url + #anchor to create external links

12. ITA base URLs by language:

    • Russian: https://itautonomos.com/ru/
    • Ukrainian: https://itautonomos.com/ua/
    • English: https://itautonomos.com/ (default language)
    • Spanish: https://itautonomos.com/es/

13. Analyze the article for ITA-relevant topics:

    • Autónomo/freelancer topics: taxes, gestors, invoicing, business registration
    • Look for mentions that ITA covers but SLG doesn't
    • Consider what ITA-specific info would help the reader

14. Apply conservative linking rules for external links:

    • Max 2-3 external links per article - even more selective than internal
    • Only link truly relevant topics - ITA is about autónomo/business, not general life
    • Don't duplicate - if topic is covered in SLG, prefer internal link
    • Skip generic terms - only link specific ITA topics like "IRPF", "Renta", "хестор", "аутономо" etc.

15. Edit the file to add external links with {:target="_blank"}

Phase 4: Summary

16. Output summary:

    Added Internal Links (SLG)

    Text linked	Link	Reason
    phrase	#anchor or /path/ or /path/#anchor	why this link helps

    Added External Links (ITA)

    Text linked	Full URL	Reason
    phrase	https://itautonomos.com/...	why this link helps

    Skipped

    • Terms considered but not linked (and why)

Example

For a Russian article about document requirements, after editing:

Added Internal Links (SLG):

Text linked	Link	Reason
юристу	#надежные-миграционные-юристы	Links to immigration lawyers
ипотеку	/ru/mortgage/	Links to mortgage guide
документы для ипотеки	/ru/mortgage/#документы-для-ипотеки	Links to mortgage documents section

Added External Links (ITA):

Text linked	Full URL	Reason
renta	https://itautonomos.com/ru/#годовая-декларация-renta	Годовая декларация (Renta)

Skipped:

• "документы" - too generic, multiple related sections
• "специалисты" - would be a self-link (article topic)