{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"create-code-walkthrough","__idx":0},"children":["Create code walkthrough"]},{"$$mdtype":"Tag","name":"ConfigOptionRequirements","attributes":{"products":["Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The code walkthrough feature is an authoring tool for creating dynamic, interactive guides that manage user's focus as they scroll."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In a code walkthrough, content is displayed across two distinct panels."," ","The panels are side-by-side, but each serves a different purpose."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["left panel"]}," displays steps and explanations that guide users through the code examples shown on the right panel."," ","This content is created using Markdown and multiple ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/code-walkthrough"},"children":["Markdoc tags"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["right panel"]}," displays code examples and highlights the specific section of code related to the current step in the left panel."," ","Highlights are managed using ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/code-walkthrough#chunk-annotations"},"children":["chunk"]}," annotations in the example code."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-begin","__idx":1},"children":["Before you begin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure you have the following:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["example code files you plan to use"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"organize-content","__idx":2},"children":["Organize content"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add code examples to your project as individual files."," ","Redocly recommends storing the code walkthrough's example files together in the same folder, as in the following example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"treeview","data-title":"Example project structure","header":{"title":"Example project structure","controls":{"copy":{}}},"source":"your-awesome-project/\n├── create-web-page/\n│ ├── _filesets/\n│ │ ├── index.html\n│ │ ├── styles.css\n│ │ ├── scripts.js\n│ │ └── README.md\n│ └── index.md\n├── ...\n└── redocly.yaml\n","lang":"treeview"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The reason we recommend storing all example files together is so that you can ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/realm/config/ignore"},"children":["ignore"]}," them in the project configuration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ignore-example-files","__idx":3},"children":["Ignore example files"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Exclude code example files from the project build using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ignore"]}," configuration in your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," file."," ","This exclusion prevents code examples from being parsed as content, ensuring they behave only as a data source for a code walkthrough."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ignore files individually or as a folder, as in the following example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"redocly.yaml","header":{"title":"redocly.yaml","controls":{"copy":{}}},"source":"ignore:\n # Ignore folder and all files in it\n - '**/_filesets/**/*'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After adding and ignoring the code example files, you're ready to add a code walkthrough to a Markdown page."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"add-a-code-walkthrough","__idx":4},"children":["Add a code walkthrough"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before writing content, use the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/code-walkthrough"},"children":["code-walkthrough tags"]}," to render a basic code walkthrough showing a single example code file and minimal content."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This step ensures the code examples are configured correctly, making it easier to spot errors when creating code walkthrough content."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code-walkthrough"]}," tag referencing one of your example code files, as in the following example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","data-title":"create-web-page/index.md","header":{"title":"create-web-page/index.md","controls":{"copy":{}}},"source":"\n{% code-walkthrough\n filesets=[\n { \"files\": [ \"examples/index.html\"] }\n ]\n%}\n # Code Walkthrough\n\n Code walkthrough content goes here.\n{% /code-walkthrough %}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/minimal-codewalkthrough-611a03753bfc3f21.png","alt":"A screenshot of the project using a single file and the smallest required configuration","framed":true,"withLightbox":true},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Restart the development preview and look at the page to verify the code walkthrough rendered successfully."," ","You should see a side-by-side panel render on the page showing the code example."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"add-files-and-categories","__idx":5},"children":["Add files and categories"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Complete any remaining configuration of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code-walkthrough"]}," tag, which may include the following tasks:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add more code example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["files"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Organize content using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include \"download-only\" files using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["downloadAssociatedFiles"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example includes multiple example files, a filter, and download-only files:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","data-title":"create-web-page/index.md","header":{"title":"create-web-page/index.md","controls":{"copy":{}}},"source":"{% code-walkthrough\n filesets=[\n { \n \"files\": [\"./code-samples/go/server.go\"],\n \"downloadAssociatedFiles\": [\"./code-samples/go/*\"],\n \"when\": { \"backend\": \"Go\" }\n },\n { \n \"files\": [\"./code-samples/node/server.js\"],\n \"downloadAssociatedFiles\": [\"./code-samples/node/*\"],\n \"when\": { \"backend\": \"Node\" }\n },\n { \n \"files\": [\"./code-samples/python/server.py\"],\n \"downloadAssociatedFiles\": [\"./code-samples/python/*\"],\n \"when\": { \"backend\": \"Python\" }\n }\n ],\n filters={\n \"backend\": {\n \"label\": \"Backend\",\n \"items\": [\n { \"value\": \"Go\" },\n { \"value\": \"Node\" },\n { \"value\": \"Python\" },\n ],\n }\n }\n%}\n # Code Walkthrough\n\n Code walkthrough content goes here.\n{% /code-walkthrough %}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/advanced-codewalkthrough-2660a0517f9b1f25.png","alt":"A screenshot of the project using multiple example files, a group label, and a download-only file","framed":true,"withLightbox":true},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Verify the following behaviors in your walkthrough before writing content:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Filenames for a code example show at top of right panel."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Clicking a filename changes the code in right panel."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["(Optional) ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filesets"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters"]}," configured to add any user-facing filters."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"add-steps-for-left-panel","__idx":6},"children":["Add steps for left panel"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Define a section in the left panel by wrapping content with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["step"]}," tag."," ","Each step must have a unique ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As the user scrolls, the \"active step\" changes and applies custom styling to that section of content."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows how steps are used in a walkthrough:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","data-title":"create-web-page/index.md","header":{"title":"create-web-page/index.md","controls":{"copy":{}}},"source":"{% code-walkthrough ... %}\n \n ## Define document head\n\n {% step id=\"head-tag\" heading=\"Add head tag\" %}\n Add a `` tag to the `index.html` file.\n {% /step %}\n\n ## Add elements to head\n\n {% step id=\"page-title\" heading=\"Set page title\" %}\n Use the `` tag to set the title of your page.\n {% /step %}\n\n {% step id=\"link-css\" heading=\"Link CSS styles\" %}\n Use the `<link>` tag to import custom styling.\n {% /step %}\n <!-- ...other steps and content -->\n{% /code-walkthrough %}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"chunks-for-right-panel","__idx":7},"children":["Chunks for right panel"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/code-walkthrough#chunk-annotations"},"children":["chunks annotation"]}," to control which lines are highlighted in the right panel when a step becomes active in a code walkthrough."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Define a section in the right panel by wrapping part of the code example with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly-chunk"]}," annotations."," ","Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["steps"]}," attribute to connect that section of code with specific steps."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As the user scrolls, the chunk is highlighted when the corresponding step(s) become active."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows chunk annotations used in a walkthrough's code example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","data-title":"create-web-page/examples/index.html","header":{"title":"create-web-page/examples/index.html","controls":{"copy":{}}},"source":"<!DOCTYPE html>\n<html lang=\"en\">\n<!-- @chunk {\"steps\": [\"head-tag\"]} -->\n<head>\n <meta charset=\"UTF-8\">\n <!-- @chunk {\"steps\": [\"page-title\"]} -->\n <title>Walkthrough example\n \n \n \n \n\n\n\n