View source for Module:AutoLinker/doc

== AutoLinker Documentation ==

This page documents the '''AutoLinker''' tool, which automatically finds and links existing wiki page titles in input text.

== Installation Instructions ==

=== Step 1: Create the Lua Module ===

# Go to your wiki's Module namespace: <code>Module:AutoLinker</code>
# Copy the complete Lua code into the page (see [[Module:AutoLinker|the module page]])
# Save

=== Step 2: Create the Template Wrapper ===

# Go to your wiki's Template namespace: <code>Template:AutoLinker</code>
# Copy the template code below into the page
# Save

=== Step 3: Customize the Page List ===

# Edit <code>Module:AutoLinker</code>
# Modify the <code>p.getStaticPages()</code> function
# Add/remove page titles that should be auto-linked
# Save

== Basic Usage ==

=== Method 1: Direct Invoke (Recommended) ===

Use this syntax anywhere on your wiki:

<syntaxhighlight lang="wiki">
{{#invoke:AutoLinker|linkify|text=Your text goes here}}
</syntaxhighlight>

The system will automatically link all matching page titles from your configured list.

'''Example:'''

Input:
<syntaxhighlight lang="wiki">
{{#invoke:AutoLinker|linkify|text=This discusses Targeted Individuals and Directed Energy Weapons.}}
</syntaxhighlight>

Output:
<syntaxhighlight lang="wiki">
This discusses [[Targeted Individuals|Targeted Individuals]] and [[Directed Energy Weapons|Directed Energy Weapons]].
</syntaxhighlight>

=== Method 2: Using the Template ===

<syntaxhighlight lang="wiki">
{{AutoLinker|input=Your text here}}
</syntaxhighlight>

This displays the form interface for processing text.

=== Method 3: Embedding in an Article ===

You can embed AutoLinker directly in article sections:

<syntaxhighlight lang="wiki">
== Linked Section ==

{{#invoke:AutoLinker|linkify|text=Paste your article text here}}
</syntaxhighlight>

== Advanced Parameters ==

When calling the module directly, you can use optional parameters:

<syntaxhighlight lang="wiki">
{{#invoke:AutoLinker|linkify
|text=Your text
|mode=static
}}
</syntaxhighlight>

; text : The input text to process (required)
; mode : Where to get the page list
:* <code>static</code> — Use curated list only (fast, requires maintenance)
:* <code>dynamic</code> — Query wiki API (slower, more complete)
:* <code>auto</code> — Try dynamic first, fall back to static (default)

== Customizing the Page List ==

To add or remove pages from auto-linking:

# Edit <code>Module:AutoLinker</code>
# Find the <code>p.getStaticPages()</code> function
# Add new pages to the return table:

<syntaxhighlight lang="lua">
return {
    "Your Page Title",
    "Another Page",
    -- etc
}
</syntaxhighlight>

=== Tips ===

* Add both singular and plural forms if needed
* Longer titles are automatically matched first
* Use proper capitalization (must match your page titles exactly)
* Test with <code>{{#invoke:AutoLinker|test|text=Sample text}}</code>

== Finding Pages to Add ==

To find your actual wiki page titles:

# Go to [[Special:AllPages]]
# Review all pages
# Copy exact titles (watch capitalization!)
# Paste into the <code>getStaticPages()</code> function

'''Important:''' Page titles must match exactly, including capitalization and spacing.

== Configuration Options ==

Edit <code>Module:AutoLinker</code> to adjust behavior:

<syntaxhighlight lang="lua">
local config = {
    caseSensitive = false,      -- Match "AI" and "ai"?
    wholeWordsOnly = true,      -- Must be standalone words
    skipAlreadyLinked = true,   -- Don't re-link [[existing]] links
    minLength = 2,              -- Skip 1-character matches
    maxMatches = 500,           -- Safety limit per invocation
    cacheExpiry = 3600,         -- Cache time in seconds
}
</syntaxhighlight>

=== Recommended Settings ===

For most wikis:
* <code>wholeWordsOnly = true</code> — Prevents matching partial words
* <code>skipAlreadyLinked = true</code> — Prevents double-linking
* <code>maxMatches = 500</code> — Safe limit for performance

== Debugging & Testing ==

=== View All Matched Pages ===

To see the complete list of pages that will be auto-linked:

<syntaxhighlight lang="wiki">
{{#invoke:AutoLinker|listPages}}
</syntaxhighlight>

This outputs a numbered list of all pages in the matching configuration.

=== Test with Sample Text ===

To test the module with sample text:

<syntaxhighlight lang="wiki">
{{#invoke:AutoLinker|test|text=Targeted Individuals and COINTELPRO}}
</syntaxhighlight>

=== Test with Custom Text ===

To test with your own text:

<syntaxhighlight lang="wiki">
{{#invoke:AutoLinker|test|text=Your sample text here}}
</syntaxhighlight>

== Common Use Cases ==

=== Processing a New Article ===

'''Workflow:'''

# Write your article
# Use AutoLinker to add links to all relevant pages
# Copy the linked output
# Paste back into your article
# Save

'''Example:'''

<syntaxhighlight lang="wiki">
== Draft Section ==

Original text: "This discusses surveillance programs, electromagnetic harassment, and targeted individuals."

{{#invoke:AutoLinker|linkify|text=This discusses surveillance programs, electromagnetic harassment, and targeted individuals.}}

== Result ==

Copy the output above and use it in your article.
</syntaxhighlight>

=== Batch Processing Multiple Articles ===

Create a temporary page in your [[Special:Sandbox|sandbox]] or [[Help:Contents|user workspace]] for processing multiple texts:

<syntaxhighlight lang="wiki">
== Text Processing Queue ==

=== Article 1 ===
{{#invoke:AutoLinker|linkify|text=First article text here}}

=== Article 2 ===
{{#invoke:AutoLinker|linkify|text=Second article text here}}

=== Article 3 ===
{{#invoke:AutoLinker|linkify|text=Third article text here}}
</syntaxhighlight>

Process all at once, then copy and distribute results.

== Limitations & Behavior ==

* '''Already linked text''' is skipped — won't double-link <code>[[existing links]]</code>
* '''Maximum 500 matches per invocation''' — safety limit to prevent performance issues
* '''Whole words only''' — matches "Energy Weapons" but not partial words
* '''Static mode is fast''' — dynamic mode slower on large wikis
* '''Case sensitivity''' — can be configured in the module

== Performance Notes ==

; Static mode (50-100 pages) : Instant
; Static mode (500+ pages) : Noticeable delay (1-2 seconds)
; Text length (10KB) : Fast
; Text length (100KB+) : Consider breaking into chunks
; Dynamic mode : 1-5 seconds typical (not recommended)

'''Optimization Tip:''' If processing very long texts, run AutoLinker on sections separately.

== Troubleshooting ==

=== Nothing is Getting Linked ===

'''Diagnosis:'''
<syntaxhighlight lang="wiki">
{{#invoke:AutoLinker|listPages}}
</syntaxhighlight>

This shows all pages in the matching list.

'''Solutions:'''
* Check that page titles in the static list exactly match your wiki pages
* Verify the module is in the <code>Module:</code> namespace
* Test with <code>{{#invoke:AutoLinker|test}}</code>
* Capitalization and spacing must match exactly

=== Too Many False Matches ===

'''Solution:'''
* Remove overly generic terms from the list
* Put longer, more specific titles first (already done by default)
* Increase specificity of page titles
* Adjust matching configuration options

=== Scribunto Error ===

'''Likely Cause:''' Syntax error in the Lua code or module not found

'''Fix:'''
# Go to <code>Module:AutoLinker</code>
# Look for red error text
# Click the error to see details
# Fix the Lua code or reinstall the module

=== Pages with Special Characters Not Linking ===

Pages with <code>[</code>, <code>]</code>, <code>(</code>, <code>)</code>, etc. need special handling.

'''Workaround:''' Add alternate titles to your list:

<syntaxhighlight lang="lua">
"The Radiohead Protocol",
"Radiohead Protocol",  -- Alternative for matching
</syntaxhighlight>

== Complete Workflow Example ==

=== Scenario: Processing an Article About Surveillance ===

'''Original Article Text:'''

<pre>
This exposé examines Targeted Individuals, Gang Stalking, and Directed Energy Weapons technology. It draws on COINTELPRO documents and recent research into Psychotronics.
</pre>

'''Processing:'''

<syntaxhighlight lang="wiki">
{{#invoke:AutoLinker|linkify|text=This exposé examines Targeted Individuals, Gang Stalking, and Directed Energy Weapons technology. It draws on COINTELPRO documents and recent research into Psychotronics.}}
</syntaxhighlight>

'''Result (after saving):'''

<pre>
This exposé examines [[Targeted Individuals|Targeted Individuals]], [[Gang Stalking|Gang Stalking]], and [[Directed Energy Weapons|Directed Energy Weapons]] technology. It draws on [[COINTELPRO|COINTELPRO]] documents and recent research into [[Psychotronics|Psychotronics]].
</pre>

'''Final Step:''' Copy the result and paste it into your article.

== Creating a Tool Page ==

To give all editors easy access to AutoLinker, create a page like <code>Tools:AutoLinker</code> or <code>Help:AutoLinker</code>:

<syntaxhighlight lang="wiki">
__NOTOC__

== Auto-Linking Tool ==

This tool automatically links all matching page titles in your text.

=== How to Use ===

Paste your text into the invoke below and save the page to see the linked result:

{{#invoke:AutoLinker|linkify|text=Replace this with your text}}

=== Instructions ===

# Write or paste your text after <code>text=</code>
# Save the page
# View the result with all matching pages linked
# Copy the linked text and paste into your article

=== Need Help? ===

* Test the tool: <code>{{#invoke:AutoLinker|test}}</code>
* View all linkable pages: <code>{{#invoke:AutoLinker|listPages}}</code>
* See all configuration: Edit [[Module:AutoLinker]]
</syntaxhighlight>

== Advanced: Modifying the Module ==

The module can be extended with custom features:

* '''Add custom filters''' — Skip pages from certain categories
* '''Change link format''' — Hide the page title in display text
* '''Add exclusion list''' — Pages that should never be auto-linked
* '''Implement dynamic page list''' — Query all wiki pages automatically

These modifications require editing the Lua code in [[Module:AutoLinker]], but the structure is straightforward.

== API Reference ==

=== Functions ===

; <code>linkify(frame)</code> : Main function; takes text and mode parameters; returns linked text
; <code>getAllPages(mode)</code> : Retrieves page list; mode can be "static", "dynamic", or "auto"
; <code>getStaticPages()</code> : Returns curated page list for matching
; <code>getDynamicPages()</code> : Queries wiki API for pages (currently simplified)
; <code>listPages(frame)</code> : Debug function; lists all pages being matched
; <code>test(frame)</code> : Test function; runs linkify with sample text

=== Configuration Variables ===

; <code>caseSensitive</code> : Boolean; whether matching is case-sensitive (default: false)
; <code>wholeWordsOnly</code> : Boolean; whether to match whole words only (default: true)
; <code>skipAlreadyLinked</code> : Boolean; whether to skip already-linked text (default: true)
; <code>minLength</code> : Number; minimum length of page titles to match (default: 2)
; <code>maxMatches</code> : Number; maximum matches per invocation (default: 500)
; <code>cacheExpiry</code> : Number; cache expiration time in seconds (default: 3600)

== See Also ==

* [[Help:Contents]] — General wiki help
* [[Help:Formatting]] — Wiki markup formatting
* [[Help:Templates]] — Template usage guide
* [[Help:Links]] — Link formatting guide
* [[Special:AllPages]] — View all pages on this wiki

== Questions or Issues? ==

For help with AutoLinker:

* Check the [[#Troubleshooting|Troubleshooting section]] above
* Run <code>{{#invoke:AutoLinker|listPages}}</code> to debug
* Review the [[Module:AutoLinker|module code]] (commented)
* Ask on the [[Project:Community Portal|Community Portal]]