Update the README generator to allow custom content anywhere throughout the README

[briangallagher]

The issue at the moment is that custom content can only be created after the generated content. This can create an unnatural flow in the README given that sections such as Additional Resources are created in the generated content.

Proposal

Maintain the existing README generation but allow custom content markers throughout the README.

More Detail

On first generation (no README):

• Render the full README from the template, All headings + auto markers + auto content.

<!-- auto-overview:start -->
Generated content here
<!-- auto-overview:end --> 

repeat for generated sections 

Editing for custom content

• Allow custom-content markers to be added anywhere to the README such as:

<!-- custom-quick-start:start -->
Add custom content here
<!-- custom-quick-start:end --> 

On check (fix=False):

• Render expected README from template.
  • For each auto section:
    • Assert both markers exist in the existing README.
    • Extract and compare only the body between markers to the expected body.
    • If any auto section is missing or mismatched → “Out of sync” (CI fails).
    • Ignore everything outside auto blocks (i.e. custom content).

On fix (fix=True):

• If all markers exist:

  • Replace bodies between markers with the expected ones (keep everything else).

• If any required marker is missing or malformed:

  • Overwrite only the auto scaffold from the template (title + headings + auto blocks), leaving custom blocks that are clearly outside that scaffold.

[CodeVishal-17]

Hi @briangallagher 👋
I’d like to work on this issue.
I’ll start by reviewing the current README generator implementation and propose an approach for handling custom-content markers cleanly.
Please let me know if that sounds good.

[briangallagher]

@CodeVishal-17 yes, thank you. We just need some 👍 from some of the maintainers before starting.
@nsingla what do you think?