Snowflake Guides(SFGuides) are interactive tutorials and self-serve demos written in markdown syntax. SFGuides provide a unique step-by-step reading experience and automatically saves tutorial progress for readers. These tutorials are published at guides.snowflake.com
You can submit your own SFGuide to be published on Snowflake's website by submitting a pull request to this repo. This repository contains all the tools and documentation you’ll need for building, writing, and submitting your own SFGuide!
- Powerful and flexible authoring flow in Markdown text
- Ability to produce interactive web or markdown tutorials without writing any code
- Easy interactive previewing
- Usage monitoring via Google Analytics
- Support for multiple target environments or events (conferences, kiosk, web, offline, etc.)
- Support for anonymous use - ideal for public computers at developer events
- Looks great, with a responsive web implementation
- Remembers where the student left off when returning to a sfguide
- Mobile friendly user experience
- Install Node; Homebrew installed?
brew install node
- Install gulp-cli
npm i -g gulp-cli
- Install gulp-cli
- Install Go; Homebrew installed?
brew install golang
- Install claat
go get github.com/googlecodelabs/tools/claat
- Install claat
- Optional: install the live-reload plugin for Chrome: LiveReload
- Fork this repository to your personal github account (top right of webpage,
fork
button) - Clone your new fork
git clone [email protected]:<YOUR-USERNAME>/sfguides.git sfguides
- Navigate to the site directory
cd sfguides/site
- Install node dependencies
npm install
- Run the site
npm run serve
Congratulations! You now have the Snowflake Guides landing page running.
- You get a
claat not found
error- Make sure Go is properly in your
PATH
. Add the following lines to your profile (~/.profile
, or~/.zshrc
):
- Make sure Go is properly in your
#adding Golang to path
export PATH=$PATH:/usr/local/go/bin
export PATH=$PATH:$HOME/go/bin
Note: After adding Go to your PATH
, be sure to apply your new profile: source ~/.profile
or source ~/.zshrc
- You get a
EACCES
error when installing gulp-cli- This means that your npm location needs to be updated. Follow the steps here: Resolve EACCESS permissions
- Terminate the running server with
ctrl C
and and navigate to thesfguides
source directorycd sfguides/src
- In this directory, you will see all existing guides and their markdown files.
- Generate a new guide from the guide template
npm run template <GUIDE_NAME>
- Don't use spaces in the name of your guide, instead use underscores.
- Navigate to the newly generated guide (
cd sfguides/src/<GUIDE_NAME>
) and edit your guide in a tool like vscode. - Run the website again
npm run serve
- As you edit and save changes, your changes will automatically load in the browser.
You can always read the sample SFGuide online.
- Review the sample.md file to learn more about to to structure your SFGuide for the claat tool.
- You can see the supported SFGuide categories here. If you want to suggest a new category please create a github issue!
- Checkout how to use VS Code to write markdown files
- If you want to learn more about SFGuides, check out this excellent tutorial
How do I get my Snowflake Guide on guides.snowflake.com?
- You will need to sign Snowflake's CLA
- Fork this repository
- Clone it to your local system
- Make a new branch
- Make your changes
- Push it back to your repo
- Open this repository on GitHub.com
- Click the Pull Request button to open a new pull request
- Snowflake will review and approve the submission
To learn more how to submit a pull request on GitHub in general, checkout github's official documentation.