Code samples in tutorial

Questions General
1

I have a quick question about the octane guide preview. There are code samples here, which are amazingly formatted, with highlights of lines of codes, and diffs a-la-git, and I was wondering what is the tool that is being used to produce that. It is awesome!

For instance, in Ember.js Guides - Guides and Tutorials - Ember Guides, the app/templates/index.hbs file.

Thanks!!

2

See GitHub - ember-learn/super-rentals-tutorial

@chancancode has been doing a lot of work in this area. The infrastructure is quite cool. The whole tutorial gets built by actually running through all the steps and recording the output. That lets us confirm in CI that nothing in the tutorial gets broken.

3

Hi @brucou! I thought this would be fun to look at myself so I poked around the site using ember inspector as well as the source code for the tutorial site. It looks like there is some “compile time” work done to transform git patches into the code snippets you see in the rendered docs, and by then they’re basically just markdown. For example in the README here is the section describing the patch snippets and some of said snippets in the raw source markdown file.

Looking at Ember Inspector it’s using a <GuidesPage /> component to render the entire page from markdown, and the snippet (from the compiled markdown) which you mentioned above looks like this:

```js { data-filename="app/templates/index.hbs" data-diff="-1,-2,+3,-7,+8" }
<div class="jumbo">
  <div class="right tomster"></div>
<Jumbo>
  <h2>Welcome to Super Rentals!</h2>
  <p>We hope you find exactly what you're looking for in a place to stay.</p>
  <LinkTo @route="about" class="button">About Us</LinkTo>
</div>
</Jumbo>

Then it looks like ember-cli-showdown is being used to render the markdown, and then for highlighting (via ember-prism, it appears) and the fancy stuff like filename and the diff +/- markers it is using some custom code in this component.

EDIT: yeah what @ef4 said :smile:

4

Even the screenshots are captured by the build process. It’s very neat.

5

oh wow, that is pretty advanced indeed and a great work. I don’t see so often code samples like this, and it is indeed very helpful to have the diff, and also to have the title of the file on top on the code sample. I have been using Hexo and a few other static site generators for docs, and none of them propose something as advanced for code sample.