Add Linear Algebra Documentation - Initial Vectors Section

.github/copilot-instructions.md

@@ -1,8 +1,10 @@
 # Copilot Instructions for Linear_Algebra
 
-## Project Architecture
+> **Note:** These instructions serve as the canonical basis for other repositories in the Julia Math study project. Documentation patterns, LaTeX conventions, and MathJax3 configuration documented here should be referenced by related repositories.
 
-This is a **Julia linear algebra computing project** using DrWatson for reproducibility, focused on geometric transformations and linear algebra operations with visualization capabilities. The codebase follows a **modular mathematical library pattern** with comprehensive testing and documentation.
+## Project Overview
+
+This is a **Julia linear algebra project** using DrWatson for reproducibility, focused on geometric transformations and linear algebra operations with visualization capabilities. The codebase follows a **modular mathematical library pattern** with comprehensive testing and documentation.
 
 ### Core Components
 
@@ -14,7 +16,10 @@ This is a **Julia linear algebra computing project** using DrWatson for reproduc
 
 ## Critical Development Patterns
 
-### Module Structure
+### Module Structure & Exports
+
+All code uses `@reexport` pattern and exports both computational + plotting functions:
+
 ```julia
 # Main module uses @reexport for clean interface
 using Reexport
@@ -38,12 +43,17 @@ export distance_2_points, center_of_gravity, barycentric_coord, plot_param_line
 # ... matrix functions, line functions, etc.
 ```
 
-### Environment-Aware Module Loading
+### Automatic CI/Interactive Detection
+
+Module auto-configures at load time - no manual intervention needed:
+
 ```julia
-# The module automatically detects CI vs interactive environments
+# src/Math_Foundations.jl - Runs on module load
 if haskey(ENV, "CI") || get(ENV, "GKSwstype", "") == "100"
     ENV["GKSwstype"] = "100"  # Headless plotting
     gr(show=false)
+else
+    gr()  # Interactive plotting
 end
 ```
 
@@ -312,14 +322,131 @@ distance_to_implicit_line(a::Number, b::Number, c::Number, r::Point) -> Float64
 foot_of_line(P::Point, v::Vector, R::Point) -> Tuple(Point, Float64)
 ```
 ## Documentation Patterns
-- Use LaTex for all mathematical notation
-- Use Markdown for explanations
-- After creating or editing a markdown document always review and fix all linting issues, unless the document is a configuration file of some kind
+
+### Structure for Mathematical Concept Documentation
+
+Documentation in `docs/src/` explains general math concepts (not code). Follow these patterns:
+
+**Document Organization:**
+- Start with concept overview and [MathWorld](https://mathworld.wolfram.com/) link in opening paragraph
+- Use hierarchical headings: `##` for major topics, `###` for subtopics
+- Group related concepts logically
+- Include real-world applications section
+
+**Content Style:**
+- **Definitions first**: Clear, precise mathematical definitions with MathWorld links
+- **Define before use**: All terms must be defined before they are used elsewhere in the document. This principle drives the order and structure of sections—ensure logical progression where each concept builds only on previously defined terms.
+- **Build progressively**: Simple concepts → complex relationships → applications
+- **Multiple representations**: Equations, tables, visual aids (SVG diagrams when helpful)
+- **Context matters**: Explain _why_ concepts are important, not just _what_ they are
+- **Derivations**: Show mathematical reasoning step-by-step
+
+**Mathematical Notation:**
+- Use LaTeX: `$$` for display equations, inline with `$...$`
+- **CRITICAL**: `$$` display blocks in Documenter.jl must have `$$` directly attached to content (no blank lines or return after opening or before closing)
+  - ✅ **CORRECT** (multi-line aligned block):
+    ```
+    $$\begin{aligned}
+    b &= a\sqrt{1-e^2} \\
+    c &= ae \\
+    a^2 &= b^2 + c^2
+    \end{aligned}$$
+    ```
+  - ✅ **CORRECT** (single equation): `$$equation$$`
+  - ❌ **WRONG** (blank lines or return between `$$` and content):
+    ```
+    $$
+
+    content
+
+    $$
+    ```
+- **Bullet point style**: List items starting with `-` must begin with **text**, then LaTeX math. LaTeX commands immediately after `-` render incorrectly (misaligned or broken formatting)
+  - ✅ **CORRECT**: `- The semi-major axis is $a$`
+  - ✅ **CORRECT**: `- stretch the vector: $\lvert c \rvert \gt 1$`
+  - ❌ **WRONG**: `- $a$ is the semi-major axis` (LaTeX immediately after dash)
+  - ❌ **WRONG**: `- $\mathbf{e}_1 = \lbrack 1, 0 \rbrack$ (points along x-axis)` (LaTeX starts the line)
+- **Equation placement style**: Prefer inline equations with "where:" at end of sentence, followed by list
+  - ✅ **CORRECT**: `For an ellipse: $\frac{x^2}{a^2} + \frac{y^2}{b^2} = 1$ where:`
+  - ❌ **AVOID**: Blank line, then equation block, then blank line, then "where:"
+- LaTeX syntax for symbols: `^\circ` not `°`, `\frac{}{}` for fractions
+- Label variables clearly: "where: $r$ = radius, $θ$ = angle"
+- Use aligned equations: `\begin{aligned}...\end{aligned}` for multi-step derivations
+- **Square brackets in LaTeX math**: Use `\lbrack` and `\rbrack` instead of `[` and `]` inside math expressions to avoid markdown link interpretation errors
+  - ✅ **CORRECT**: `$\mathbf{v} = \lbrack v_1, v_2 \rbrack$`
+  - ❌ **WRONG**: `$\mathbf{v} = [v_1, v_2]$` (markdown interprets `[v_1, v_2]` as a link)
+- **Absolute value notation**: Use `\lvert` and `\rvert` instead of `|` to avoid markdown pipe interpretation
+  - ✅ **CORRECT**: `$\lvert c \rvert > 1$`
+  - ❌ **WRONG**: `$|c| > 1$` (pipe may be interpreted as table delimiter)
+
+**MathJax3 Configuration (Linear_Algebra uses MathJax3 instead of default KaTeX):**
+
+This project uses MathJax3 for math rendering. Key configuration in `docs/make.jl`:
+
+```julia
+mathengine = Documenter.MathJax3(Dict(
+    :loader => Dict("load" => ["[tex]/physics", "[tex]/ams"]),
+    :tex => Dict(
+        "packages" => ["base", "ams", "mathtools"],
+        "inlineMath" => [["\$", "\$"]],
+        "displayMath" => [["\$\$", "\$\$"], ["\\[", "\\]"]],
+    ),
+)),
+```
+
+**Critical**: The `displayMath` array must include **both** `$$...$$` AND `\[...\]` delimiters because:
+- Markdown source uses `$$...$$` for display math
+- Documenter.jl converts some `$$` blocks to `\[...\]` in generated HTML (especially in list items or new paragraphs)
+- Without both delimiters, MathJax won't process `\[...\]` blocks and they render as literal text
+
+**To switch from KaTeX to MathJax3:**
+1. Add `mathengine` parameter to `Documenter.HTML()` in `docs/make.jl`
+2. Include both delimiter styles in `displayMath`
+3. Load desired packages (ams, mathtools, physics) via `:loader` and `"packages"`
+4. Clean rebuild: `rm -rf docs/build && julia --project=. docs/make.jl`
+
+**MathWorld Links:**
+- Link every new mathematical term on first mention
+- Format: `[Term](https://mathworld.wolfram.com/Term.html)`
+- Verify URLs before adding (use fetch_webpage)
+- Compare multiple URLs to choose most appropriate
+
+**Visual Elements:**
+- SVG diagrams for geometric concepts
+- Tables for reference data (common values, conversions)
+- Consistent styling in diagrams (colors, labels, annotations)
+
+**Markdown Conventions:**
+- _Underscore_ for emphasis (not asterisk)
+- **Bold** for important terms and section labels
+- Fix all linting issues after editing (except config files)
+- Code blocks with language tags: ````julia` for Julia examples
 - Follow the pattern of existing function documentation in src directory
-- When a new mathematical concept is introduced, add an external link to [MathWorld](https://mathworld.wolfram.com/) for that specific concept.
-  - Compare multiple potential URLs to choose the most appropriate one
-  - Avoid replacing working links with inferior alternatives
-  - Always use fetch_webpage function to check the link is valid and points to the correct concept.
+
+**Cross-Document Section Links (Documenter.jl):**
+
+When linking to a specific section in another document, use standard markdown link syntax with the full file path and section anchor:
+
+```markdown
+[Display Text](../Folder/Document Name.md#Section-Heading)
+```
+
+**CRITICAL rules for section anchors:**
+- Section anchors must **exactly match** the heading text with proper capitalization
+- Spaces in **file names** remain as spaces (not `%20`)
+- Spaces in **section anchors** become hyphens (`-`)
+- Parentheses in section names are preserved in the anchor
+
+**Examples:**
+- ✅ **CORRECT**: `[Coordinate Independent Operations](../Geometry/01 Points and Coordinates.md#Coordinate-Independent-Operations)`
+- ✅ **CORRECT**: `[Linear Independence (Geometric View)](../Geometry/01 Points and Coordinates.md#Linear-Independence-(Geometric-View))`
+- ❌ **WRONG**: `[Section](../Geometry/01%20Points%20and%20Coordinates.md#section)` (wrong: `%20` and lowercase)
+- ❌ **WRONG**: `[Section](@ref "Section Name")` (`@ref` is for docstrings, not cross-document links)
+
+**Best practice for cross-references:**
+- Include context about which document contains the section: "see [Section Name](path#anchor) in Document Name"
+- Verify the section heading spelling and capitalization before creating the link
+- Test the link by building docs (`julia --project=. docs/make.jl`) and clicking in browser
 
 ## Communication Patterns
 

.gitignore

@@ -417,4 +417,7 @@ $RECYCLE.BIN/
 ## Acknowledgements
 # Many thanks to `https://gitignore.io/`, written and maintained by Joe Blau, which contributed much material to this gitignore file.
 
-/Manifest.toml
+/Manifest.toml
+docs/src/Linear\ Algebra\ Old/
+docs/src/Linear Algebra Capacities/
+

.markdownlint-cli2.jsonc

@@ -0,0 +1,5 @@
+{
+    "ignores": [
+        ".github/copilot-instructions.md"
+    ]
+}

docs/make.jl

@@ -6,15 +6,45 @@ using Linear_Algebra
 makedocs(;
     modules=[Linear_Algebra],  # Specify your module here
     sitename = "Linear_Algebra",
+    # pagesonly=true excludes all markdown files not listed in pages (e.g., Linear Algebra Capacities/)
+    pagesonly = true,
     # This argument is only so that the sequence of pages in the sidebar is configured
-    # By default all markdown files in `docs/src` are expanded and included.
-    pages = ["index.md", "sites.md"],
+    pages = [
+        "index.md",
+        "Basics" => [
+            "Basics/01 Vectors.md",
+            # "Basics/02 Linear Transformations.md",
+            # "Basics/03 Matrices.md",
+            # "Basics/04 Systems of Equations.md",
+        ],
+        "Geometry" => [
+            "Geometry/01 Points and Coordinates.md",
+            # "Geometry/02 Lines.md",
+            # "Geometry/03 Dot Product and Orthogonality.md",
+            # "Geometry/04 Projections and Distance.md",
+            # "Geometry/05 Line Intersections.md",
+            # "Geometry/06 Transformations.md",
+            # "Geometry/07 Matrices and Maps.md",
+            # "Geometry/08 Linear Systems.md",
+            # "Geometry/09 Inverse and Kernel.md",
+            # "Geometry/10 3D Geometry.md",
+        ],
+        "sites.md"
+    ],
     # Don't worry about what `CI` does in this line.
     format = Documenter.HTML(
         prettyurls = CI,
         edit_link = "main",
         assets = ["assets/custom.css"],
         inventory_version = "0.1.0",
+        mathengine = Documenter.MathJax3(Dict(
+            :loader => Dict("load" => ["[tex]/physics", "[tex]/ams"]),
+            :tex => Dict(
+                "packages" => ["base", "ams", "mathtools"],
+                "inlineMath" => [["\$", "\$"]],
+                "displayMath" => [["\$\$", "\$\$"], ["\\[", "\\]"]],
+            ),
+        )),
         footer = "Powered by [Documenter.jl](https://documenter.jl) and the [Julia Programming Language](https://julialang.org) generated on $(Dates.format(Dates.now(), "yyyy-mm-dd HH:MM:ss"))"
     ),
 )