md-to-svelte/README.md

Convert markdown file to svelte.

# Markdown to svelte
Convert markdown file to svelte pages.

## Installation
To install `md-to-svelte` run any of the following commands.
```bash
npm i md-to-svelte@latest
```
or
```bash
pnpm add md-to-svelte@latest
```

## How to use package
To get started using `md-to-svelte` you will need to do the following steps.
- Use function, import  `vitMdToSvelte` from `md-to-svelte`.
- Create `pages` directory to markdown files.

To use package, let's start by importing the default function from `md-to-svelte`.
```js
import mdToSvelte from "md-to-svelte";
```
Or import the vite plugin
```js
import {viteMdToSvelte } from "md-to-svelte";
```
Create a folder `pages` in your current working directory and create all your md files there.<br />
The function returns the following result + create svelte kit pages to the given outputDir.

### Add vite plugin
```ts
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
// import viteMdToSvelte plugin
import { viteMdToSvelte } from 'md-to-svelte';

export default defineConfig({
	plugins: [
        // add it to plugins
        viteMdToSvelte("src/routes/blog/","DevelopedByAnt"),
        sveltekit()
    ]
});
```

### Pages directory
In your working directory create `pages` folder, once that is created you can add all you markdown 
files that will be converted to svelte pages in there.<br />
All markdown files are required to have the following tags at the top of the file.
```text
---
layout: File layout
title: Page title
description: Page description.
---
```
The key `layout` indicates what group the current file being converted belongs too, 
`title` the title for the svelte page, `description` description for page, optional `new` it's if you are creating a documentation website and you just added a new feature to add a badge next to the link and `image` add image meta tag to page.
```text
---
layout: File layout
title: Page title
description: Page description.
new: true
image: https://metatags.io/images/meta-tags.jpg
---
```

#### Simple markdown page
```markdown
    ---
    layout: Introduction
    title: MdToSvelte
    description: Convert markdown file to svelte pages.
    ---

    # Markdown to svelte
    Convert markdown file to svelte pages.

    ## Installation
    To install `md-to-svelte` run any of the following commands.
    ```bash
    npm i md-to-svelte@latest
    ```
    ```bash
    pnpm add md-to-svelte@latest
    ```
```

## Returned data
You can also import the default function from `` and it will create routes and return the following data back.
```ts
// This will convert all files in `pages` folder to routes @ "src/routes/docs/".
const result = await mdToSvelte("src/routes/docs/")

/** Data returned from function */
type Result = {
    /** Page layout key */
    [key:string]:{
        /** Page link (href) */
        href:string
        /** Page title */
        title:string
        /** Page description */
        description:string
        /** Indicate if it's a new feature (add badge next to link) */
        new:boolean
    }[]
}
```

## Customize styles
To add or customize the element tags generated by us, you will need to create a global style and add the following styles.
```css
:root {
    --shiki-background: #202020;
    --shiki-foreground: #9CDCFE;
    --shiki-token-constant: #4EBEFB;
    --shiki-token-string: #CE9178;
    --shiki-token-comment: #6A9955;
    --shiki-token-keyword: #C586C0;
    --shiki-token-parameter: #D16969;
    --shiki-token-function: #DCDCAA;
    --shiki-token-string-expression: #C586C0;
    --shiki-token-punctuation: #D4D4D4;
    --shiki-token-link: #75BEFF;
    /* added by us */
    --shiki-button-bg: #2f2f2f;
    --shiki-button-color: #a9a9a9;
}

/* headers */
[data-md="header"]{
    color: var(--header-color);
    margin-bottom: 5px;
}
h1[data-md="header"]{
    font-size: 35px;
    font-weight: 900;
}
h2[data-md="header"]{
    font-size: 25px;
    font-weight: 800;
}
h3[data-md="header"]{
    font-size: 20px;
    font-weight: 400;
}
h4[data-md="header"],h5[data-md="header"]{
    font-size: 20px;
    font-weight: 400;
}

/* paragraph */
[data-md="p"]{
    font-size: 15px;
    font-weight: 400;
    color: var(--text-color);
    gap: 5px;
    margin: 10px 0;
}

/* anchor (link) */
[data-md="a"]{
    text-decoration: none;
    font-size: 15px;
    font-weight: 600;
}

/* space */
[data-md="space"]{
    margin-bottom: 20px;
}

/* list */
[data-md="list"],[data-md="list-ordered"]{
    margin-left: 20px;
    display: flex;
    flex-direction: column;
    gap: 5px;
    & li{
        font-size: 16px;
        font-weight: 400;
        color: var(--text-color);
    }
}

/* inline code */
[data-md="inline-code"]{
    display: inline-flex;
    align-items: center;
    width: fit-content;
    gap: 5px;
    background-color: var(--code-bg);
    color: var(--code-text-color);
    font-size: 13px;
    font-weight: 400;
    padding: 3px 6px;
    border-radius: 5px;
}

/* code */
[data-md="code"]{
    position: relative;
    margin: 5px 0px;
    border-radius: 5px;
    padding: 10px 0px;
    background: var(--shiki-background);
    font-size: 14px;
    font-weight: 300;
    & button{
        all: unset;
        cursor: pointer;
        background-color: var(--shiki-button-bg);
        color: var(--shiki-button-color);
        padding: 5px 8px;
        border-radius: 4px;
        position: absolute;
        top: 5px;
        right: 5px;
        display: flex;
        align-items: center;
        justify-content: center;
        font-size: 10px;
    }
    & code {
        flex: 1;
        display: flex;
        flex-direction: column;
    }
    & .line{
        padding: 1px 10px;
        margin: 2px 0px;
    }
    & .line.added{
        background-color: var(--code-line-added-bg);
        margin: 0px;
    }
    & .line.removed{
        background-color: var(--code-line-removed-bg);
        margin: 0px;
    }
}

/* warning */
[data-md="warning"]{
    padding: 10px;
    border-radius: 10px;
    font-size: 16px;
    font-weight: 300;
    border: 1.5px solid var(--border-color);
    color: white;
    background-color: #be7575;
    display: flex;
    align-items: center;
    gap: 10px;
    & svg{
        min-width: 20px;
        min-height: 20px;
        width: 20px;
        height: 20px;
        fill: var(--error-bg);
    }
}

/* mobile =========================================== */
@media (max-width: 768px) {
    /* paragraph */
    [data-md="p"]{
        font-size: 13px;
    }
    /* headers */
    h1[data-md="header"]{ font-size: 30px; }
    h2[data-md="header"]{ font-size: 25px; }
    h3[data-md="header"]{ font-size: 20px; }
    /* anchor (link) */
    [data-md="a"]{
        font-size: 13px;
    }
    /* warning */
    [data-md="warning"]{
        font-size: 13px;
    }
}
```
### Code block
To style the code blocks you can use [Shiki's theme colors](https://shiki.style/guide/theme-colors), we use the css variables so you can customize the easily.
```css
:root {
    --shiki-background: #202020;
    --shiki-foreground: #9CDCFE;
    --shiki-token-constant: #4EBEFB;
    --shiki-token-string: #CE9178;
    --shiki-token-comment: #6A9955;
    --shiki-token-keyword: #C586C0;
    --shiki-token-parameter: #D16969;
    --shiki-token-function: #DCDCAA;
    --shiki-token-string-expression: #C586C0;
    --shiki-token-punctuation: #D4D4D4;
    --shiki-token-link: #75BEFF;
    /* added by us */
    --shiki-button-bg: #2f2f2f;
    --shiki-button-color: #a9a9a9;
}
```