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://architecture.pivotal.io/guides.

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

1. Clone the cosmos web app from https://github.com/pivotal-cf/cosmos.

2. If you are working on macro edits, create a fork in your own github space from https://github.com/pcf-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 cosmos app locally, but with the following tweak:

Example 1. cosmos-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 cosmos 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 pcf-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. cosmos won’t run

   Before you dig in and start editing guides, first make sure you can run cosmos locally. Try ./gradlew :cosmos-site:run

2. I don’t see my edits!

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