main.go

Add a new test function following the existing Test* naming convention. Study how existing tests like those checking alphabetical ordering or duplicate detection parse the README.md content line by line

Pattern: See how existing test functions in main_test.go use Go's testing.T, read README.md content, iterate over lines, and call t.Errorf for violations. Each validation rule is its own Test* function

If your validation needs helper functions, add them as unexported functions in the same file, following the pattern of existing helper functions that parse markdown lines or extract link data

Pattern: Look at existing helper functions in main_test.go that extract URLs, parse list items, or check formatting — add your helper in the same style with clear parameter names and return values

Study the existing stale repository detection logic to understand how it extracts GitHub URLs from README.md and queries the GitHub API. Add your new health check as a new Test* function or extend the existing staleness check

Pattern: Follow the pattern in stale_repositories_test.go where GitHub URLs are extracted from the README, the GitHub API is called for each repository, and results are reported via t.Errorf with the repo URL and reason for failure

If your check requires new GitHub API fields (e.g., license info, stargazers_count), extend the API response struct or add a new API call following the existing HTTP request pattern with proper authentication headers

Pattern: See how stale_repositories_test.go constructs GitHub API requests with authorization headers and parses JSON responses into Go structs. Add new fields to the existing response struct or create a new one

Study this file as the reference pattern for creating a new utility package. Note the package declaration, exported function signatures, and how it provides a single focused utility

Pattern: pkg/slug/generator.go defines a focused package with a clear exported function. Your new package should follow the same structure: pkg/<name>/<name>.go with a clear package declaration and exported functions with Go doc comments

Study this file as a second reference for a slightly more complex utility package that may have dependencies. Note how it handles custom configuration (heading ID generation)

Pattern: pkg/markdown/convert.go shows how to wrap an external library with custom behavior. If your utility wraps a third-party library, follow this pattern of providing a clean exported API that hides implementation details

Import and integrate your new package into the site generation pipeline. Add the import path as 'github.com/<org>/<repo>/pkg/<yourpackage>' and call your exported functions at the appropriate stage of the pipeline

Pattern: See how main.go imports and uses pkg/markdown and pkg/slug — import your new package the same way and call it at the relevant pipeline stage

Modify the conversion function to add your custom rendering behavior. If adding a new rendering feature, extend the existing conversion logic or add a new exported function

Pattern: See how convert.go already implements custom heading ID generation — follow the same approach of hooking into the markdown rendering pipeline to add your custom behavior (e.g., custom link renderer, code block handler)

If your change requires new configuration or a new function call, update main.go to pass the configuration or call the new function during the site generation pipeline

Pattern: See how main.go calls the markdown conversion functions from pkg/markdown — add your new function call or configuration in the same pipeline stage

If your change affects how the README renders, verify that existing rendering validation tests still pass and add new test cases if needed

Pattern: Check existing rendering-related tests in main_test.go to ensure your markdown changes don't break validation

Modify the slug generation function to handle the new rules. Update character replacement maps, regex patterns, or transformation logic as needed

Pattern: See the existing character handling in pkg/slug/generator.go — extend the same approach (character maps, string replacements, regex substitutions) for your new rules

Verify that main.go's usage of the slug package still works correctly with your changes. Check all call sites where slugs are generated for categories and project names

Pattern: Search main.go for all calls to the slug package and verify each call site produces correct output with the new rules

Check if the markdown converter uses slug generation for heading IDs — if so, verify compatibility with your slug changes

Pattern: Look at how convert.go generates heading IDs and whether it uses pkg/slug or has its own logic. Ensure consistency between heading anchors and page URL slugs

Add the new page generation logic to the site generation pipeline. Study how existing pages are generated: how categories are extracted, how HTML templates are populated, and how files are written to the output directory

Pattern: Follow the existing page generation pattern in main.go: extract data from parsed markdown → apply HTML template → write output file. Add your new page at the appropriate stage of the pipeline

If your new page requires different markdown processing (e.g., extracting specific sections), add a new exported function to the markdown package

Pattern: See how convert.go provides conversion functions — add a new function that extracts or transforms the specific markdown content your new page needs

If your new page needs URL slugs for new types of content, verify the slug generator handles them correctly

Pattern: Test the slug generator in pkg/slug/generator.go with sample names from your new content type to ensure proper URL generation