Improve GitHub and npm discoverability documentation #4

Activity

1. adrianbrowning

   marked this as blocked on Aug 8, 2026

   • Define the canonical npm package identity and align metadata #3
2. adrianbrowning commented on Aug 8, 2026

   

   adrianbrowning

   on Aug 8, 2026

   OwnerAuthor

   More actions

   This was generated by AI during triage.

   Agent Brief

   Category: enhancement
   Summary: Make mdcode discoverable and immediately usable from its repository landing page and published documentation.

   Current behavior:
   The public README is mainly a development reference. It does not provide the canonical package installation command, a source-to-Markdown quick start, detailed user documentation, or clear product positioning. Package and repository metadata still need to converge on the canonical package identity.

   Desired behavior:
   A prospective user can understand mdcode, install the canonical package, follow one short source-first documentation example, and find complete command and library documentation. All public-facing repository and package metadata consistently use the approved identity @gcmdev/mdcode.

   Key interfaces:

   • Public README and documentation entry points — explain mdcode as source-first Markdown synchronization and provide a concise end-to-end example.
   • Published package metadata — description, keywords, repository, homepage, and npm links must support relevant discovery and reflect the canonical identity.
   • Repository discoverability configuration — document the recommended GitHub topics for a maintainer to apply.

   Acceptance criteria:

   • The README states the product purpose and source-first workflow in language suitable for prospective users.
   • The README gives the canonical @gcmdev/mdcode installation command and a short, accurate end-to-end example.
   • The README links to complete CLI and library documentation, or adds the minimum needed documentation entry points where none exist.
   • Published package/repository metadata and public documentation consistently name @gcmdev/mdcode.
   • Keywords and recommended GitHub topics cover Markdown code-block authoring, documentation synchronization, and docs-as-code discovery terms.
   • The documented example and commands are checked against the current public CLI contract.

   Out of scope:

   • Publishing @gcmdev/mdcode or deprecating mdcode-ts; those account-level release actions remain in issue Define the canonical npm package identity and align metadata #3.
   • Applying GitHub repository topics when maintainership permissions are required; document the exact recommended set instead.
   • New CLI behavior, parser changes, or validation features.

   Verification status:
   Confirmed: the current README is development-oriented and lacks an installation/quick-start path; package metadata presently uses inconsistent identities.
3. adrianbrowning

   added

   enhancementNew feature or requestNew feature or request

   ready-for-agentFully specified and ready for an AFK agentFully specified and ready for an AFK agent

   on Aug 8, 2026
4. adrianbrowning

   added a commit that references this issue on Oct 4, 2026

   docs: improve GitHub and npm discoverability (#4) (#33)

   0fc1422
5. adrianbrowning

   closed this as completedin #33on Oct 4, 2026