Upload files to "docs"

docs/api.md

@@ -0,0 +1,223 @@
+# API Documentation
+
+This document provides detailed documentation for the GemReader application's internal APIs and code structure.
+
+## Package Structure
+
+- `main` (cmd/gemreader/main.go): Application entry point and command-line interface
+- `config` (internal/config/config.go): Configuration loading and management
+- `tui` (internal/tui/tui.go): Terminal user interface implementation
+
+## Main Package
+
+### main.go
+
+#### Execute() function
+
+```go
+func Execute()
+```
+
+- Initializes and executes the Cobra command
+- Handles command execution errors
+- Exits the application with appropriate error code if execution fails
+
+#### rootCmd variable
+
+```go
+var rootCmd = &cobra.Command
+```
+
+- Main Cobra command for the application
+- Uses format: `gemreader [file]`
+- Allows 0 or 1 arguments (the markdown file to view)
+- Handles file reading and TUI initialization
+- If no file is provided, attempts to use the default file from config
+
+#### validateFilePath() function
+
+```go
+func validateFilePath(inputPath string) (string, error)
+```
+
+- Validates file paths to prevent directory traversal attacks
+- Cleans and resolves absolute paths
+- Ensures the resolved path is within the current working directory
+- Returns error if path traversal is detected
+
+#### validateFile() function
+
+```go
+func validateFile(filePath string) error
+```
+
+- Performs security checks on files before loading
+- Validates file size (max 10MB)
+- Ensures file is a supported type (.md, .markdown, .txt, or no extension)
+
+## Config Package
+
+### config.go
+
+#### Config struct
+
+```go
+type Config struct {
+    Title       string `mapstructure:"title"`
+    DefaultFile string `mapstructure:"default_file"`
+    ShowTOC     bool   `mapstructure:"show_toc"`
+}
+```
+
+- Stores application configuration
+- Supports Title, DefaultFile, and ShowTOC fields
+- Tagged for Viper configuration mapping
+
+#### LoadConfig() function
+
+```go
+func LoadConfig() (config Config, err error)
+```
+
+- Loads configuration from config.toml file
+- Searches for config file in current directory
+- Supports TOML format
+- Returns Config struct and error if any
+- Uses Viper for configuration management
+- Returns defaults if config file doesn't exist
+
+## TUI Package
+
+### tui.go
+
+#### model struct
+
+```go
+type model struct {
+    content         string
+    rawLines        []string
+    toc             []tocEntry
+    selectedTocIndex int
+
+    tocViewport     viewport.Model
+    contentViewport viewport.Model
+
+    activePane   pane
+    helpVisible  bool
+    config       config.Config
+    windowWidth  int
+    windowHeight int
+}
+```
+
+The model struct contains all state information for the TUI:
+
+- `content`: Original markdown content as string
+- `rawLines`: Original content split by newlines for TOC generation
+- `toc`: Table of contents entries
+- `selectedTocIndex`: Index of currently selected TOC entry
+- `tocViewport`: Bubble Tea viewport for TOC pane
+- `contentViewport`: Bubble Tea viewport for content pane
+- `activePane`: Currently active pane (TOC or content)
+- `helpVisible`: Whether help text is visible
+- `config`: Application configuration
+- `windowWidth`, `windowHeight`: Terminal dimensions
+
+#### pane type
+
+```go
+type pane int
+
+const (
+    tocPane pane = iota
+    contentPane
+)
+```
+
+- Represents the two panes in the UI
+- `tocPane`: Left pane showing table of contents
+- `contentPane`: Right pane showing markdown content
+
+#### tocEntry struct
+
+```go
+type tocEntry struct {
+    level int
+    text  string
+    line  int
+}
+```
+
+- Represents a single entry in the table of contents
+- `level`: Header level (1 for #, 2 for ##, etc.)
+- `text`: Text content of the header
+- `line`: Line number in the original document
+
+#### NewModel() function
+
+```go
+func NewModel(content string, cfg config.Config) model
+```
+
+- Creates a new TUI model with the given content and configuration
+- Splits content into lines for TOC generation
+- Generates table of contents from headers
+- Initializes viewport models
+- Sets up initial state with content pane as active
+
+#### generateTOC() function
+
+```go
+func generateTOC(lines []string) []tocEntry
+```
+
+- Scans content lines for markdown headers
+- Creates tocEntry for each header found
+- Determines header level based on number of # characters
+- Returns list of all headers in document order
+
+#### (m model) Init() method
+
+```go
+func (m model) Init() tea.Cmd
+```
+
+- Bubble Tea initialization method
+- Returns nil command (no initial command needed)
+
+#### (m model) Update() method
+
+```go
+func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd)
+```
+
+- Bubble Tea update method for handling messages and user input
+- Handles window resize events and recalculates pane dimensions
+- Processes keyboard input for navigation
+- Switches between TOC and content panes with Tab key
+- Handles TOC navigation and jumping to selected entries
+- Updates both viewport models
+- Supports all navigation commands
+
+#### (m model) View() method
+
+```go
+func (m model) View() string
+```
+
+- Bubble Tea view method for rendering the UI
+- Applies styles to active and inactive panes
+- Renders both TOC and content panes side by side
+- Shows help text at the bottom if visible
+- Returns string representation of current UI state
+
+#### (m model) renderTOC() method
+
+```go
+func (m model) renderTOC() string
+```
+
+- Renders the table of contents view
+- Shows headers with proper indentation based on level
+- Highlights the currently selected entry with '>'
+- Shows "No table of contents found." if no headers exist