Split into a multi page site using Vitepress

[OceanIsEndless]

Fixes #2, and is a continuation of pull request #3. Vitepress has now been set up, but only a couple major sections have been split so far. Much more is to come! Thanks to @gradylink for helping along the process.

[gradylink]

run npm install and make sure to commit the package-lock.json file (it'll fix the action)

[gradylink]

ok revert the ./ to / that is really wrong and revert the base option.

[gradylink]

it's kinda funny 'cause you'll keep trying things until you see this...

[OceanIsEndless]

run npm install and make sure to commit the package-lock.json file (it'll fix the action)

ok revert the ./ to / that is really wrong and revert the base option.

Oh, ok. I'll try it! :]

it's kinda funny 'cause you'll keep trying things until you see this...

Ah, yes. Glad I stopped when I did lol. 😅

Whenever things don't work I usually just try whatever until it does. Doesn't always work though... :)

[OceanIsEndless]

Hmm, seems like it needs to install vitepress or something?? Sorry I'm dumb lol

[gradylink]

You have npm/node installed right?

EDIT: base should be /scratch-spec

EDIT 2: run npm i vitepress then commit/push what changed.

EDIT 3: you can also test locally without pushing to github by running npm run docs:dev.

[OceanIsEndless]

You have npm/node installed right?

Yep!

base should be /scratch-spec

Okay.

run npm i vitepress then commit/push what changed.

It added node_modules, which I guess must be an essential component?... and it added a bunch of stuff to the package-lock.json! I have a good feeling about this now. (Seemed like something was missing there.)

you can also test locally without pushing to github by running npm run docs:dev.

I managed to do this before and it worked fine on my machine, and it still works now. The challenge is getting it to work on GitHub... 🤔

[gradylink]

I've never seen that error before...

[OceanIsEndless]

Progress was made! Now it's complaining about my images :>

[gradylink]

It added node_modules, which I guess must be an essential component?... and it added a bunch of stuff to the package-lock.json! I have a good feeling about this now. (Seemed like something was missing there.)

just don't commit and push node_modules.

[OceanIsEndless]

just don't commit and push node_modules.

I've already added it to the .gitignore! Was able to tell it shouldn't be there from your original pull.

I've never seen that error before...

Uh-oh

Maybe it's something to do with how the images were put in the markdown? (idk, the error seems to be referencing them)

#### Rotation Style: All Around

![A demonstration of the "all around" rotation style](/img/all-around.gif)

#### Rotation Style: Left-Right

![A demonstration of the "left-right" rotation style](/img/left-right.gif)

#### Rotation Style: Don't Rotate

![A demonstration of the "don't rotate" rotation style](/img/don't-rotate.gif)

Edit: Looking closer it seems to be a problem with importing the images? ¯\_(ツ)_/¯

[gradylink]

yeah, i'll see if I can figure it out. Also I think I might make a custom markdown extension to handle scratchblocks code blocks.

EDIT: you should delete the 2 markdown files in .vitepress/

EDIT 2: replace {{toc}} with [[toc]]

[OceanIsEndless]

yeah, i'll see if I can figure it out. Also I think I might make a custom markdown extension to handle scratchblocks code blocks.

Epic!

you should delete the 2 markdown files in .vitepress/

Apologies, I have no idea why I thought moving the example files to the config dir wouldn't cause any issues 🥲

replace {{toc}} with [[toc]]

Shoot, I thought I caught that.

[OceanIsEndless]

I went back to the docs, maybe this is the problem?
https://vitepress.dev/guide/asset-handling#referencing-static-assets

Common image, media, and font filetypes are detected and included as assets automatically.

PDFs or other documents referenced by links within markdown files are not automatically treated as assets. To make linked files accessible, you must manually place them within the public directory of your project.

Maybe it's not recognizing the .gifs or something dumb like that? Just throwing out ideas. I might try omitting the images for now and see if it works.

[OceanIsEndless]

It doesn't like my broken heading links either 8>

It says I can disable the check for them though... gonna try it

[OceanIsEndless]

This is why I don't like deployments lol

Seems to be just a permissions issue now though. The build worked! Might have misconfigured something in the repository that is stopping the deployment. Just trying to get it deployed, and then it can be refined later.

[OceanIsEndless]

Fixed settings issue with deploying (I think; random answer online), going to manually run and see if it will deploy!

[OceanIsEndless]

...I lack the mental capacity to run it manually, triggering by push 😐

[gradylink]

OK, i got the markdown-it plugin to work but all the blocks are black for some reason?

EDIT: of course it doesn't work only on vitepress

EDIT 2: now it just deletes everything on the page!

[gradylink]

OK I got it working. What you need to do is run npm install sb-mdit and then replace your .vitepress/config.mts with:

import { defineConfig } from 'vitepress'
import { scratchblocksPlugin } from 'sb-mdit'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  title: "Scratch Specification",
  base: "/scratch-spec/", // https://vitepress.dev/guide/deploy#setting-a-public-base-path
  ignoreDeadLinks: true,

  themeConfig: {
    // https://vitepress.dev/reference/default-theme-config
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Intro', link: '/intro/' },
      { text: 'Concepts', link: '/concepts/' },
      { text: 'Runtime', link: '/runtime/' },
      { text: 'Blocks', link: '/palette/' },
      { text: 'Files', link: '/files/' },
      { text: 'I/O', link: '/io/' },
      { text: 'Network', link: '/network/' },
      { text: 'Devices', link: '/devices/' }
    ],

    sidebar: [
      {
        text: 'Introduction',
        link: '/intro/',
        items: [
          { text: 'Frequently Asked Questions', link: '/intro/#faq' },
          { text: 'Contributing Guidelines', link: '/intro/#contributing' }
        ]
      },
      {
        text: 'Concepts',
        link: '/concepts/',
        items: [
          { text: 'Capabilities', link: '/concepts/#capabilities' },
          { text: 'Constants', link: '/concepts/#constants' },
          { text: 'Ideas', link: '/concepts/#ideas' },
          { text: 'Values', link: '/concepts/#values' },
          { text: 'Procedures', link: '/concepts/#procedures' }
        ]
      },
    ],

    socialLinks: [
      { icon: 'github', link: 'https://github.com/OceanIsEndless/scratch-spec' }
    ],

    search: {
      provider: 'local'
    }
  },
  markdown: {
    config: md => md.use(scratchblocksPlugin)
  }
})

[OceanIsEndless]

Hooray, the blocks plugin works great! I also figured out how to make it render math, and with scratchblocks rendering and Vitepress and everything, it all looks very nice now. Thank you so much for making this happen! I've got a lot of writing to do.

Should be able to merge soon (and probably will have to so as not to confuse people, as it's already deployed to Pages lol). Might try and fix the image files real quick and then it's good to go.

[gradylink]

Oh, another suggestion. Move contents onto its own page. It's kind weird on the homepage

[gradylink]

You should submit a bug to vitepress about the image issue.

[OceanIsEndless]

I'll merge this now (before I forget and start writing the entire thing from this branch)... it looks good to me sooooooooo yay! Thank you for all the help, splitting it up was a necessary change and things should be going more smoothly from here on out :D

[OceanIsEndless]

oh shoot

[OceanIsEndless]

there :D

[gradylink]

yay!