An API to handle markdown

[sacrosanctic]

edit: see #982 (comment) for update. Please thumbs up if there's interest.

We might as well redo the whole readme.

[jycouet]

Maybe some part, but maybe not all?!
Maybe another hook?

[manuel3108]

In what form would that be useful? Why cant you just scroll up in the terminal? If you are working in a team, you should rewrite the readme either way.

[sacrosanctic]

Terminal is ephemeral, I often clear it or close it, resorting to rerunning the command to see it. The "next steps" we print in the terminal is essentially the same info for a "getting started" section. Giving the user a template to start editing in a team environment.

We are otherwise left with https://github.com/sveltejs/cli/blob/main/packages/sv/src/create/shared/README.md. Leaves a lot to be desired.

[manuel3108]

Related #956

[sacrosanctic]

Basically, i see these as tasks you will want to run more than once (on a different machine, shared with other people)

• better-auth
  • npm run auth:schema
  • npm run db:push
• demo page
• drizzle
  • npm run wrangler d1 create <db_name>
  • db:start
• playwright
  • npx playwright install
• cloud-flare adapter
  • npm run gen

Proposal

add another hook, or accept an object

nextSteps: ({ isKit }) => {
	const steps: string[] = [];

	steps.push(`Run ${color.command('npx playwright install')} to download browsers`);

	if (isKit) {
		steps.push(`Visit ${color.route('/demo/playwright')} to see the demo page`);
	}

	steps.push(`Run ${color.command('npm run test:e2e')} to execute the example tests`);

	// accept string[]
	return steps;
	// or object
	return { console:steps, readme:steps.slice(0,1)}
}

---

Seperately, add a section in the README.md to look at .env.example if it exists

[sacrosanctic]

Here is where we're at after some experimentation.

---

sv.file('README.md`, transforms.md(({ md }) => {
  md.upsert(
  // selector
  '## Add-on Info > my-add-on',
  // lines to insert, will filter out falsy values
  [
    'Step 1',
    'Step 2',
    check && 'Maybe step 3',
    array.length && "Maybe step 4',
  ])
})

---

Selector can handle variable depth. Will modify the first one found if there are duplicates.

md.upsert("## Level 2 > Level 3",...)
md.upsert("# Level 1 > Level 2 > Level 3",...)
md.upsert("#### Level 4",...)

---

The markdown itself can be built entirely from md.upsert or from a template.

EXAMPLE.md

## Usage

To install the add-on, run:

```sh
npx sv add {{protocolName}}
```

md.template('EXAMPLE.md', {
  protocaolName: projectName.startsWith('@') 
    ? projectName.split('/')[0] 
    : projectName;
})

---

What's missing

Parser

A parser is needed to implement the selector. Here is a list of potential options.

• remark
• marked
• markdown-exit
• comark
• pngwn's upcoming markdown parser

Considerations: should be lightweight.

fromCommand

We only want to run this during create. Currently, fromCommand is an internal API.

References

Previous explorations

• feat(sv): add setup instructions to README.md #1034
• md draft sacrosanctic/cli#3