Testing edits to your guide and macros

So you’ve written a guide and/or worked on some macros to support it? The trick with guides is that you have to publish them to view them at http://spring.io/guides.

We’ve got you covered! On this page, you can see how to test things locally before you commit.

1. Clone the sagan web app from https://github.com/spring-io/sagan.

2. If you are working on macro edits, create a fork in your own github space from https://github.com/spring-guides/getting-started-macros.

3. Assuming your new guide is in your own space, you are ready to test things out.

In essence, you will run the sagan app locally, but with the following tweak:

Example 1. sagan-site/src/main/resources/application.yml

...
  guides:
    owner:
      name: ${GITHUB_GUIDES_OWNER_NAME:/*your githubusername*/}
      type: ${GITHUB_GUIDES_OWNER_TYPE:users}
...

With that edit, now when you run sagan and visit http://localhost:8080/guides/gs/<guide&gt;, it will fetch from http://github.com/<githubusername>/gs-<guide&gt;. This makes it very easy to test things locally.

Important

Don’t forget. If you use a standard macro, you will have traveled back to spring-guides. To test your own variation, replace the path to the macro with a path to your clone hosted on github.

What’s that? It didn’t work? Here are some debugging scenarios to try:

1. sagan won’t run

   Before you dig in and start editing guides, first make sure you can run sagan locally. There is an entire wiki dedicated to this at https://github.com/spring-io/sagan/wiki.

2. I don’t see my edits!

   Any and all edits to guides or macros must be pushed up to your version. Sagan NEVER looks at your local file system when rendering things.