Snowflake Quickstarts
What are Snowflake Quickstarts?
Snowflake Quickstarts are interactive tutorials and self-serve demos written in markdown syntax. Quickstarts provide a unique step-by-step reading experience and automatically saves tutorial progress for readers. These tutorials are published at quickstarts.snowflake.com
You can submit your own Quickstarts 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 Quickstart!
What's special about the Quickstart format?
- 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 quickstarts
- Mobile friendly user experience
Getting Started
Prerequisites
- Install Node 14; Homebrew installed?
brew install node@14
- Install gulp-cli
npm i -g gulp-cli
- Install gulp-cli
- Install Go; Homebrew installed?
brew install golang
- Install claat
go install github.com/googlecodelabs/tools/claat@latest
- Ensure go and claat is in your
PATH
claat path setup
- Install claat
- Optional: install the live-reload plugin for Chrome: LiveReload
Run locally
- Fork this repository to your personal GitHub account (top right of webpage,
fork
button) - Clone your new fork
git clone [email protected]:<YOUR-USERNAME>/sfquickstarts.git sfquickstarts
- Navigate to the site directory
cd sfquickstarts/site
- Install node dependencies
npm install
- Run the site
npm run serve
- Open a browser to http://localhost:8000/
Congratulations! You now have the Snowflake Quickstarts landing page running.
Common Errors
1. Claat related errors
- Make sure Go is properly in your
PATH
. Add the following lines to your profile (~/.profile
, or~/.zshrc
):
#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
EACCES
error when installing gulp-cli
2. You get a - This means that your npm location needs to be updated. Follow the steps here: Resolve EACCESS permissions
Error: Cannot find module 'postcss'
when running npm run serve
3. You get - The module may not have been installed for some reason so run
npm install --save-dev postcss gulp-postcss
and then rerunnpm run serve
Write Your First Quickstart
- Terminate the running server with
ctrl C
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 VS Code. - 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 Quickstart online.
Tips
- Review the sample.md file to learn more about how to structure your Quickstart for the claat tool.
- You can see the supported Quickstart 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 Quickstarts, check out this excellent tutorial
quickstarts.snowflake.com?
How do I get my Snowflake Quickstart on- 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 about how to submit a pull request on GitHub in general, check out GitHub's official documentation.
Reporting issues or errata in Quickstarts
If you encounter an issue in a Quickstart (outdated copy or data, typos, broken links, etc.), please file an issue. Be sure to include the following information:
- The title of the Quickstart
- A link to the Quickstart
- A description of the problem
- A proposed solution, if applicable (optional)