Suggestion: Add brief contextual descriptions to list items, or convert lists to tables #5

New Issue

GiteaMirror · 2025-11-06T08:11:54-06:00

GiteaMirror commented

2025-11-06 08:11:54 -06:00

Originally created by @hey-august on GitHub (May 2, 2024).

This list could be enhanced with little impact to usability by the addition of a short explanatory sentence after each bullet point.

Example

Site Generators

Antora - Docs-as-code SSG for AsciiDoc

Asciidoctor - text processor publishing toolchain for AsciiDoc, exporting to many web and print formats

Docusaurus - Powerful docs-as-code SSG for Markdown and Markdown React (MDX) designed for docs sites

Astro - Web framework and SSG with docs template (see Starlight) with support for Markdown, MDX, Markdoc

This adds additional context without making the lists overly bloated.

Table format example

While this would entail a larger reorganization of content, a table format could be implemented to organize additional information about items.

Site Generators

Site Generator Open-source? Supported languages Notes

Antora ❌ AsciiDoc Developed by the Asciidoctor maintainers

Asciidoctor ✅ AsciiDoc Run with Ruby or JS

Docusaurus ✅ Markdown, Markdown React (MDX) Docs-focused SSG

Astro ✅ Markdown, Markdown React (MDX), Markdoc Multipurpose framework and SSG; the Starlight template is designed for docs sites

This would be a more intensive reorganization. The table format adds additional organization and information capabilities, but reduces ease of maintainability.

Originally created by @hey-august on GitHub (May 2, 2024). This list could be enhanced with little impact to usability by the addition of a short explanatory sentence after each bullet point. ## Example > ### Site Generators > > - **Antora** - Docs-as-code SSG for AsciiDoc > - **Asciidoctor** - text processor publishing toolchain for AsciiDoc, exporting to many web and print formats > - **Docusaurus** - Powerful docs-as-code SSG for Markdown and Markdown React (MDX) designed for docs sites > - **Astro** - Web framework and SSG with docs template (see Starlight) with support for Markdown, MDX, Markdoc This adds additional context without making the lists overly bloated. ## Table format example While this would entail a larger reorganization of content, a table format could be implemented to organize additional information about items. > ### Site Generators > > | Site Generator | Open-source? | Supported languages | Notes | > | :--- | :--- | :--- | :--- | > | Antora | ❌ | AsciiDoc | Developed by the Asciidoctor maintainers | > | Asciidoctor | ✅ | AsciiDoc | Run with Ruby or JS | > | Docusaurus | ✅ | Markdown, Markdown React (MDX) | Docs-focused SSG | > | Astro | ✅ | Markdown, Markdown React (MDX), Markdoc | Multipurpose framework and SSG; the Starlight template is designed for docs sites | This would be a more intensive reorganization. The table format adds additional organization and information capabilities, but reduces ease of maintainability.

GiteaMirror added the enhancement label 2025-11-06 08:11:54 -06:00

GiteaMirror commented

2025-11-06 08:11:56 -06:00

@ross-spencer commented on GitHub (Dec 12, 2024):

Under requirements for your awesome-list it suggests this would be needed to be following good practice.

Entries have a description, unless the title is descriptive enough by itself. It rarely is though.

But yeah, in this issue for the same reason. Was hoping to be able to browse the list for something matching my use-case but will have to click through all the links.

@ross-spencer commented on GitHub (Dec 12, 2024): Under [requirements](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md#requirements-for-your-awesome-list) for your awesome-list it suggests this would be needed to be following good practice. > Entries have a description, unless the title is descriptive enough by itself. It rarely is though. But yeah, in this issue for the same reason. Was hoping to be able to browse the list for something matching my use-case but will have to click through all the links.

GiteaMirror referenced this issue

2025-11-06 08:12:08 -06:00

[PR #5] [MERGED] feat(gh-action) add link-check #9

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/awesome-docs#5

Site Generator	Open-source?	Supported languages	Notes
Antora	❌	AsciiDoc	Developed by the Asciidoctor maintainers
Asciidoctor	✅	AsciiDoc	Run with Ruby or JS
Docusaurus	✅	Markdown, Markdown React (MDX)	Docs-focused SSG
Astro	✅	Markdown, Markdown React (MDX), Markdoc	Multipurpose framework and SSG; the Starlight template is designed for docs sites