{"id":14959288,"url":"https://github.com/brycerussell/astro-remark-description","last_synced_at":"2025-10-24T16:31:49.948Z","repository":{"id":188756897,"uuid":"679378221","full_name":"BryceRussell/astro-remark-description","owner":"BryceRussell","description":"Automatically add a description to the frontmatter of your markdown in Astro","archived":false,"fork":false,"pushed_at":"2024-01-23T20:42:30.000Z","size":31,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-29T23:43:21.242Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BryceRussell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-16T17:47:09.000Z","updated_at":"2024-07-08T15:38:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"90f0560d-2f21-4411-8b66-d19bf289bcfd","html_url":"https://github.com/BryceRussell/astro-remark-description","commit_stats":null,"previous_names":["brycerussell/astro-remark-description"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BryceRussell%2Fastro-remark-description","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BryceRussell%2Fastro-remark-description/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BryceRussell%2Fastro-remark-description/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BryceRussell%2Fastro-remark-description/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BryceRussell","download_url":"https://codeload.github.com/BryceRussell/astro-remark-description/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238008434,"owners_count":19401255,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T13:19:20.804Z","updated_at":"2025-10-24T16:31:44.628Z","avatar_url":"https://github.com/BryceRussell.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `astro-remark-description`\n\nAutomatically add a description to the frontmatter of your markdown in Astro\n\n## How to use\n\n**1)** Install using the command `npm i astro-remark-description`\n\n**2)** Add plugin to `astro.config.mjs`\n\n```ts\nimport { defineConfig } from 'astro/config';\nimport remarkDescription from 'astro-remark-description' \n\nexport default defineConfig({\n  markdown: {\n    remarkPlugins: [\n      [remarkDescription, {}]\n    ]\n  }\n});\n```\n\n## Options\n\n### `name`\n\n**Type**: `string`\n\n**Default**: `'description'`\n\nName of key inside frontmatter\n\n---\n\n### `html`\n\n**Type**: `boolean`\n\n**Default**: `false`\n\nRender node to a string of HTML\n\n---\n\n### `override`\n\n**Type**: `boolean`\n\n**Default**: `false`\n\n- `true`: if frontmatter property already exists, replace it\n\n- `false`:  if frontmatter property already exists, skip file\n\n---\n\n### `skip`\n\n**Type**: `number`\n\n**Default**: `0`\n\nNumber of nodes to skip before grabbing text\n\nFor example, if the first pragraph contains an image, use  `{ skip: 1 }` to get the text of the next paragraph\n\n---\n\n### `node`\n\n**Type**: [`unist-util-is`](https://github.com/syntax-tree/unist-util-is#test) test\n\nTag name tests: `\"blockquote\" | \"break\" | \"code\" | \"definition\" | \"delete\" | \"emphasis\" | \"footnoteDefinition\" | \"footnoteReference\" | \"heading\" | \"html\" | \"image\" | \"imageReference\" | \"inlineCode\" | \"link\" | \"linkReference\" | \"list\" | \"listItem\" | \"paragraph\" | \"strong\" | \"table\" | \"tableCell\" | \"tableRow\" | \"text\" | \"thematicBreak\" | \"yaml\" | \"root\"`\n\n**Default**: `'paragraph'`\n\nA test for finding nodes when looping over markdown to get text\n\n---\n\n### `parent`\n\n**Type**: `'paragraph' | 'root' | 'blockquote' | 'delete' | 'emphasis' | 'footnoteDefinition' | 'heading' | 'link' | 'linkReference' | 'list' | 'listItem' | 'strong' | 'table' | 'tableCell' | 'tableRow'`\n\n**Default**: `'root'`\n\nType of the parent node\n\nFor exmaple, if the text for your description is inside a list, the parent must be `'listItem'`\n\n---\n\n### `transform`\n\nFunction to transfrom the description text before it is added to the frontmatter\n\n**Type**:\n\n```ts\ntype transform = (\n  description: string,\n  data: {\n    path: string,\n    cwd: string,\n    frontmatter: Record\u003cstring, any\u003e | undefined\n    node: Node\n  }\n) =\u003e any\n```\n\n**Example 1**:\n\nOnly use the first sentence of description text\n\n```ts\n{\n  transform: (desc) =\u003e desc.split('.')[0] + '.'\n}\n```\n\n**Example 2**:\n\nCapitalize all description text\n\n```ts\n{\n  transform: (desc) =\u003e desc.toUpperCase()\n}\n```\n\n---\n\n### `filter`\n\nA function to control the plugin options of each file\n\n**Type**:\n\n```ts\ntype filter = (\n  options: Options,\n  data: {\n    path: string,\n    cwd: string,\n    frontmatter: Record\u003cstring, any\u003e | undefined\n  }\n) =\u003e Options | false | null | undefined | void\n```\n\n**Example 1**:\n\nSkip over any files that have `scrape: false` in the frontmatter or are located inside the \"projects\" collection\n\n```ts\n{\n  filter: (options, { path, frontmatter }) =\u003e {\n    if (!frontmatter.scrape || path.startsWith('/src/content/projects'))\n      return false // Return falsey value to skip\n    return options\n  }\n}\n```\n\n**Example 2**:\n\nApply an edge case to a specific file\n\n```ts\n{\n  filter: (options, { path }) =\u003e {\n    if (path == '/src/content/blog/post-3.md')\n      options.skip = 2 // skip first 2 paragraphs\n    return options\n  }\n}\n```\n\n## Examples\n\n### Basic\n\n```ts\nimport { defineConfig } from 'astro/config';\nimport remarkDescription from 'astro-remark-description' \n\nexport default defineConfig({\n  markdown: {\n    remarkPlugins: [\n      [remarkDescription, { name: 'excerpt' }]\n    ]\n  }\n});\n```\n\n### Advanced\n\n```ts\nimport { defineConfig } from 'astro/config';\nimport remarkDescription from 'astro-remark-description' \n\nexport default defineConfig({\n  markdown: {\n    remarkPlugins: [\n      [remarkDescription, { \n        name: 'excerpt',\n        override: true,\n        // Uppercase first letter in description\n        transform: (desc) =\u003e desc[0].toUpperCase() + desc.slice(1)letter,\n        filter: (options, { path }) =\u003e {\n          // Skip file if not inside a collection\n          if (!path.startsWith('/src/content'))\n            return false\n          // Use heading for description in 'projects' collection\n          if (!path.startsWith('/src/content/projects'))\n            options.node = 'heading'\n          // Edge case: first paragraph is an image, use the second\n          if (path === '/src/content/blog/post-3.md')\n            options.skip = 1\n          return options\n        },\n      }]\n    ]\n  }\n});\n```\n\n### Using `remarkDirective` to target a node\n\n```js\nimport { defineConfig } from 'astro/config';\nimport remarkDescription from 'astro-remark-description'\nimport remarkDirective from 'remark-directive'\n\nexport default defineConfig({\n  markdown: {\n    remarkPlugins: [\n      remarkDirective,\n      [remarkDescription, { \n        node: node =\u003e node.type === 'containerDirective' \u0026\u0026 node.name === 'description'\n      }]\n    ]\n  }\n});\n```\n\n```md\n# Heading\n\nLorem, ipsum dolor sit amet consectetur adipisicing elit. Sed.\n\n:::description\nLorem, ipsum dolor sit amet consectetur adipisicing elit. Sed.\n:::\n```\n\n### Emulating other Frameworks\n\n#### Hexo\n\n[Post Excerpt](https://hexo.io/docs/tag-plugins#Post-Excerpt)\n\n```js\nimport { defineConfig } from 'astro/config';\nimport remarkDescription from 'astro-remark-description'\n\nexport default defineConfig({\n  markdown: {\n    remarkPlugins: [\n      [remarkDescription, {\n        name: 'excerpt',\n        node: (node, i, parent) =\u003e {\n          const sibling = parent?.children[i + 1]\n          return sibling?.type === 'html' \u0026\u0026 sibling?.value === '\u003c!-- more --\u003e'\n        }\n      }]\n    ]\n  }\n});\n```\n\n```md\n# Heading\n\nLorem, ipsum dolor sit amet consectetur adipisicing elit. Sed.\n\nLorem, ipsum dolor sit amet consectetur adipisicing elit. Sed.\n\n\u003c!-- more --\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrycerussell%2Fastro-remark-description","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrycerussell%2Fastro-remark-description","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrycerussell%2Fastro-remark-description/lists"}