{"id":22485135,"url":"https://github.com/walkthru/walkthru","last_synced_at":"2025-08-02T18:31:34.296Z","repository":{"id":37404068,"uuid":"504412740","full_name":"walkthru/walkthru","owner":"walkthru","description":"WalkThru is a better way of explaining code on the web.","archived":false,"fork":false,"pushed_at":"2022-07-19T23:20:21.000Z","size":4505,"stargazers_count":237,"open_issues_count":1,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2023-11-07T16:31:51.849Z","etag":null,"topics":["react","tutorial"],"latest_commit_sha":null,"homepage":"https://walkthru.netlify.app/walkthru-intro","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/walkthru.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-06-17T06:02:49.000Z","updated_at":"2023-11-01T18:35:53.000Z","dependencies_parsed_at":"2022-07-08T19:02:02.209Z","dependency_job_id":null,"html_url":"https://github.com/walkthru/walkthru","commit_stats":null,"previous_names":[],"tags_count":1,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walkthru%2Fwalkthru","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walkthru%2Fwalkthru/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walkthru%2Fwalkthru/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walkthru%2Fwalkthru/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/walkthru","download_url":"https://codeload.github.com/walkthru/walkthru/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228499927,"owners_count":17929986,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["react","tutorial"],"created_at":"2024-12-06T17:12:04.229Z","updated_at":"2024-12-06T17:13:47.175Z","avatar_url":"https://github.com/walkthru.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# WalkThru\n\n**WalkThru is a better way of explaining code on the web.**\n\n![WalkThru demo](https://media.giphy.com/media/A4McguuzE9AApZNZel/giphy.gif)\n\nCheck out the [live demo](https://walkthru.netlify.app/walkthru-intro) to see how it works.\n\nSee the [live demo source code](https://github.com/walkthru/next) if you want to see an implementation example using Next.js. \n\nFollow [on Twitter](https://twitter.com/walkthruapp) for news and updates.\n\n## Packages\n\nTo create a walkthru, you'll need to install these two packages:\n\n- **WalkThru data module** for compiling a tutorial from markdown files.\n- **WalkThru React component** for displaying a tutorial in your site or app.\n\n## WalkThru data module\n\nA WalkThru tutorial consists of multiple steps. Each step contains instructions and a code file and is defined in a separate markdown file. There is also a config file used for tutorial-wide settings.\n\nThis module is used to compile a tutorial before it is displayed in your app.\n\n### Installation\n\n```\nnpm i -D @walkthru/data\n```\n\n### Directory structure\n\nFirst, create a folder `walkthru` in the root of your app. Each tutorial should be in a separate folder e.g. `my-walkthru`.\n\nInside each tutorial, you'll need a `config.json` file. Each step of the tutorial will be in a separate markdown file e.g. `step1.md`.\n\n```\n.\n├── walkthru\n│   ├── my-walkthru\n│       └── config.json\n│       └── step1.md\n│       └── step2.md\n```\n\n### Config file\n\nHere is an example walkthru config file.\n\n```json\n{\n  \"title\": \"My Tutorial\",\n  \"code\": {\n    \"owner\": \"myname\",\n    \"repo\": \"myrepo\",\n    \"ref\": \"main\"\n  },\n  \"steps\": [\n    \"step1\",\n    \"step2\"\n  ]\n}\n```\n\nOptions:\n- `title`. The tutorial title.\n- `code`. An object where you declare the GitHub repo and files used.\n    - `owner`. Your GitHub account name.\n    - `repo`. The repo name.\n    - `ref`. The branch, tag, or commit to use.\n- `steps`. An array of step name strings. These are the names of the steps you want to include in the tutorial.\n\n### Step files\n\nEach step of the tutorial will be in a separate markdown file, like this:\n\n```markdown\n---\ntitle: My step\nfile: walkthru/my-walkthru/app.jsx\n---\n# Hello world\n```\n\nFrontmatter options:\n- `title`. The title of the step (required).\n- `file`. The repo file you want to use as the code example.\n- `language`. The language of the code example. No need to set this if the language can be determined from the file extension e.g. `js`.\n- `focus`. The line or range of lines to focus on e.g. `7`, `7-11`.\n- `center`. The line to center the code example on e.g. `9`. Tip: probably you would use the middle line of the focus range.\n- `image`\n  - `src`. The URL of the image (required if using `image`).\n  - `bgColor`. Defaults to `rgb(255,255,255)`.\n  - `borderColor`. Defaults to `rgb(229, 231, 235)`.\n\n### Usage in an app\n\nThis should be used server side. For example, in the `getStaticProps` method of Next.js or in a serverless function.\n\nFirst, import the `getData` method from the package at the top of the file. This method is async and takes two arguments: `githubToken` and `tutorialSlug`.\n\n`githubToken` is a GitHub personal access token which is used to contact the GitHub API to grab the code from your repo. You can learn how to generate one [here](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). You should probably put this in an environment variable.\n\n`tutorialSlug` is simply the name of the tutorial e.g. `\"my-tutorial\"`.\n\nThe method will compile the tutorial and return it as an object that can be passed as props to the [WalkThru React component](https://github.com/walkthru/react) to display the tutorial.\n\n```js\nimport { getData } from '@walkthru/data'\n\nconst data = await getData(githubToken, 'my-tutorial')\n```\n\n## WalkThru React component\n\n```\nnpm i -S @walkthru/react\n```\n\nRender the component anywhere in your app.\n\nNote that you'll need a way to get the `data` object from the WalkThru data module (see above).\n\n```jsx\nimport { WalkThru } from '@walkthru/react'\n\nfunction App () {\n\n  // Logic\n  \n  return (\n    \u003cWalkThru\n      data={data}\n      tutorialSlug={tutorialSlug}\n      stepSlug={stepSlug}\n      classes={{\n        instructions: ''\n      }}\n    /\u003e\n  )\n}\n```\n\n## Props\n\n- `data`. Returned from `getData`.\n- `tutorialSlug`. The slug of the current tutorial e.g. `my-tutorial`.\n- `stepSlug`. The slug of the current step e.g. `introduction`.\n- `classes`. An object that can be used to add classes to elements of the component.\n    - `instructions`. Classes to be applied to the instructions content.\n    - `select`. Classes applied to React Select.\n\n## Tips\n\n- Don't server render this component.\n- The step and tutorial slugs will usually be dynamic segments of the URL. e.g. `https://myapp.com/{tutorial-slug}#{step-slug}`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwalkthru%2Fwalkthru","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwalkthru%2Fwalkthru","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwalkthru%2Fwalkthru/lists"}