Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/netspective-labs/astro-markdown-experience
A collection of remark plugins for an enhanced Astro markdown experience
https://github.com/netspective-labs/astro-markdown-experience
Last synced: 8 days ago
JSON representation
A collection of remark plugins for an enhanced Astro markdown experience
- Host: GitHub
- URL: https://github.com/netspective-labs/astro-markdown-experience
- Owner: netspective-labs
- Created: 2023-09-11T16:51:28.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2023-09-11T18:10:40.000Z (about 1 year ago)
- Last Synced: 2024-08-11T08:09:50.785Z (3 months ago)
- Language: TypeScript
- Size: 31.3 KB
- Stars: 2
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Astro Markdown Experience
A collection of remark plugins designed to improve our markdown processing experience in Astro-based sites. There shouldn't be too much Astro-specific but we haven't had a chance to generealize and test in non-Astro contexts yet.
## Table of Contents
- [Astro Markdown Experience](#astro-markdown-experience)
- [Table of Contents](#table-of-contents)
- [Installation](#installation)
- [Remark Plugins](#remark-plugins)
- [Rewrite Previewable URL](#rewrite-previewable-url)
- [Rewrite Links](#rewrite-links)
- [Chart](#chart)
- [Diagram](#diagram)
- [Reading Time](#reading-time)
- [Validate Resources](#validate-resources)
- [Usage](#usage)
- [Contributing](#contributing)
- [License](#license)
## Installation
```bash
pnpm add astro-markdown-experience
```
## Remark Plugins
### Rewrite Previewable URL
Modify URLs to previewable versions for enhanced user experience. This allows
you to preview markdown content directly from the VS Code and automatically
rewrite any URLs to final published versions on build.
For example, if you use `./otherfile.md` in your markdown it will be rewritten
to the published URL like `https://example.com/otherfile`. This allows the local
editing and previewing experience to feel more like the final published version.
```markdown
[VS Code Previewable](./otherfile.md)
```
We want to be able to co-locate images with Markdown during editing so that
they are previewable and convenient to manage. However, during builds of
static sites or apps we want the same images to be available in the `public`
directory so that they can be served as web assets without worrying about
pretty URLs or locations. For example, this should be possible in Markdown:
```markdown
[Click Colocated Link](colocated-file-name.jpg)
```
When we process remark and publish as SSG (e.g. Astro) we automatically figure
out the location of markdown source file to copy `colocated-file-name.jpg`
into `~/public/x/y/z/colocated-file-name.jpg` where x/y/z is the relative
path of the source.
We also want to be able to store images directly in ~/public but our Markdown
files in `src/*` to be preview-friendly in the CLI and VS Code. For example,
this should be possible in Markdown:
```markdown
```
When we process using remark and publish as SSG (e.g. Astro) we don't include
the path `/public` because that's just the `dist` folder (in any SSG). So, we
rewrite them dynamically to:
```markdown
```
By default, location for _relocated files_ is `public/relocated-assets-from-content`
directory and you should add it to `.gitignore`.
```javascript
import * as ameRPU from "astro-markdown-experience/rewrite-previewable-url";
export default defineConfig({
markdown: {
remarkPlugins: [
ameRPU.typicalRemarkRewritePreviewableURLsPlugin(),
],
},
integrations: [
...
```
```javascript
import * as ameRPU from "astro-markdown-experience/rewrite-previewable-url";
export default defineConfig({
markdown: {
remarkPlugins: [
ameRPU.typicalRemarkRewritePreviewableURLsPlugin({
commonBaseURL: '/otherThanRoot'
}),
],
},
integrations: [
...
```
### Rewrite Links
Transform or modify links within your markdown.
```javascript
import rewriteLinks from 'astro-markdown-experience/rewrite-links';
```
### Chart
Describe the `chart` plugin's functionality, benefits, and use case here.
```javascript
import chart from 'astro-markdown-experience/chart';
```
### Diagram
Describe the `diagram` plugin's functionality, benefits, and use case here.
```javascript
import diagram from 'astro-markdown-experience/diagram';
```
### Reading Time
Estimate the reading time for your markdown content.
```javascript
import readingTime from 'astro-markdown-experience/reading-time';
```
### Validate Resources
Ensure all links and resources in your markdown are valid.
```javascript
import validateResources from 'astro-markdown-experience/validate-resources';
```
## Usage
Provide a more comprehensive guide on how to integrate and use the plugins in various scenarios.
## Contributing
Contributions are welcome! See the [CONTRIBUTING.md](./CONTRIBUTING.md) file for more details.
## License
MIT - see the [LICENSE](./LICENSE) file for details.