function App() {
  return (
    <div>
      <h1>WalkThru</h1>
      <p>A better way of explaining code on the web!</p>
    </div>
  )
}

export default App


---
title: WalkThru tutorials
file: walkthru/walkthru-intro/walkthru-tutorials.md
---

The steps of a tutorial created with WalkThru include text instructions (displayed here on the left side) and a code file (displayed on the right side).

Steps are defined in markdown files with YAML frontmatter.


---
title: Focusing code
file: walkthru/walkthru-intro/focusing-code.md
focus: 4-5
center: 4
---

To make it easier to explain your code, you can focus on specific lines.

To do this, set the `focus` property in the frontmatter and indicate the range of lines to focus on. 

You can also specify the `center` property which indicates which line should be in the center of the page when the step loads. (This is useful in large code files as you'll see in a moment).


---
title: Displaying an image
file: walkthru/walkthru-intro/displaying-image.md
image:
    src: github-screenshot.png
focus: 3-5
center: 4
---

In addition to code, you can also show an image in a step. 

This is useful if you want to show how code affects a UI, for example.

To do this, add the `image` property to the frontmatter and be sure to add a `src` subproperty.


What is WalkThru?

import { useEffect } from 'react'
import { WalkThru } from '@walkthru/react'
import Layout from '../components/Layout'
import NoSSR from '../components/NoSSR'

const instructionsStyle = `
  color: rgb(55, 65, 81);
  font-size: 14px;
  line-height: 24px;
  font-family: ui-sans-serif, system-ui, -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";  
  li {
    margin: 3px 0;
  }
`

function Slug({ data, slug }) {
  const { config } = data
  useEffect(() => {
    document.title = config.title
  }, [config])
  return (
    <Layout>
      <div
        className="flex w-full relative max-w-screen-xl mx-auto"
        style={{ maxHeight: '800px' }}
      >
        <NoSSR>
          <WalkThru
            data={data}
            slug={slug}
            instructionsStyle={(base) => `
              ${base}
              ${instructionsStyle}
            `}
          />
        </NoSSR>
      </div>
    </Layout>
  )
}

// This gets called at build time

import fs from 'fs'
import { getData } from '@walkthru/data'

export async function getStaticPaths() {
  const paths = fs
    .readdirSync(`walkthru`, { withFileTypes: true })
    .filter((dirent) => dirent.isDirectory())
    .map((dirent) => ({
      params: {
        slug: dirent.name,
      },
    }))
  return {
    paths,
    fallback: false,
  }
}

export async function getStaticProps({ params }) {
  const githubToken = process.env.GH_PAT
  const data = await getData({ githubToken })
  return {
    props: data.find((item) => item.slug === params.slug),
  }
}

export default Slug


Coding tutorials can be frustrating for both readers and authors.

Common issues include:

- Hard to link code examples with explanation.
- Code examples are either too long or too short.
- Errors in code examples are hard to catch.

**WalkThru** provides an easier and more accurate way of explaining code by utilizing interactive and dynamic aspects of the web.

It's open source and can be embedded in any web page for technical tutorials, documentation, or teaching.

Let's take a quick tour to find out how it works.


Introduction

The steps of a tutorial created with WalkThru include text instructions (displayed here on the left side) and a code file (displayed on the right side).

Steps are defined in markdown files with YAML frontmatter.


WalkThru tutorials

The code files used in a tutorial are downloaded from your source code to ensure accuracy. 

You can specify which file to show in each step using the `file` frontmatter property.


Including code file

To make it easier to explain your code, you can focus on specific lines.

To do this, set the `focus` property in the frontmatter and indicate the range of lines to focus on. 

You can also specify the `center` property which indicates which line should be in the center of the page when the step loads. (This is useful in large code files as you'll see in a moment).


Focusing code

In addition to code, you can also show an image in a step. 

This is useful if you want to show how code affects a UI, for example.

To do this, add the `image` property to the frontmatter and be sure to add a `src` subproperty.


Displaying an image

It's also possible to display the image only without any code. Just remove the `file` property from that step.

This is useful for when you want to show a screenshot or diagram.


Image only

Each WalkThru tutorial requires a JSON config file like this one. 

Next, we'll take a look at the important properties.


JSON config file

As mentioned, the code files are downloaded from your source code. You can specify a GitHub repo using the `code` property.

The `owner` and `repo` sub properties specify the repo, while the `ref` property specifies a particular branch, tag, or commit.


Code config

The `steps` array contains the steps you wish to include and in which order.

Note that a step is identified by its "slug" i.e. a unique ID derived from its file name.


Steps config

Okay, you've created a WalkThru tutorial. How do you now make it display in your app or docs site?

This is where you'll use the **WalkThru React component**. This component is responsible for displaying everything you see in this tutorial right now including the navigation, instructions, and code file. 

But before you can use this component, you'll need to get the compiled tutorial data into your site. Let's see how to do that first.


Displaying a walkthru

This tutorial is embedded in a Next.js static site, though you can use any framework you like.

Next has a special method `getStaticProps` for loading data needed by the page at build time. 

This is the perfect place to compile and load the tutorial data. You can do this with the `getData` method of the **WalkThru data module**.

To load the data, you'll need the *tutorial slug* and a *GitHub Personal Access Token*.


Loading data

The tutorial slug is the unique ID of your tutorial, e.g. "walkthru-intro". 

You will probably want to use this slug as a dynamic segment in the URL, e.g. "mysite.com/walthru-intro".

Next.js will pass this to `getStaticProps` as a property of the `params` argument.


Slug

Since WalkThru downloads your source code from GitHub using its API, you'll need a free [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).

It's a good idea to store this in an environment variable.


GitHub Personal Access Token

Now that you have the tutorial slug and GitHub token, you can call the asynchronous `getData` method. 

This will compile the tutorial content including the downloaded source code files and markdown content.

With that done, you can display the data in the app. 


Get data

Returning to the WalkThru component, the `data` prop should be assigned the data returned from `getData` in the previous step.

You'll also need two other props: `tutorialSlug` and `stepSlug`. These are the slugs of the current tutorial and the current step respectively.

The way you get these will be dependent on your implementation. For this site, I've made the `tutorialSlug` a dynamic route component while the `stepSlug` is a URL hash value.

You can also pass an object to the `classes` prop which will contain CSS class names that can be applied to sub-elements within the component.


WalkThru component

Thanks for checking out this introduction to WalkThru 🙏. 

You can find more info about how to use it in this [GitHub repo](https://github.com/walkthru/walkthru).

*Created by Anthony Gore. Follow me on [Twitter](https://twitter.com/anthonygore).*
