Shape Books — A TakeShape Sample Project

This is a sample project to get you started building a static website with TakeShape (TS). You can see the sample project in action here: https://shape-books.takeshapesampleproject.com/

Quickstart

1. Use the "Deploy to TakeShape" button to create the project in TakeShape.
2. Set up and run the client application
   1. git clone https://github.com/takeshape/takeshape-starter-books && cd takeshape-starter-books
   2. npm install - This will install all dependencies
   3. npm run init - A browser window should open, where you can log into or create a TakeShape account. If you encounter any errors in this process, run npm run cli-init to log into your account from the command line. Follow the command prompts to set up your local environment to communicate with TS.
   4. npm run start - The server runs on http://localhost:5000 by default
3. Have fun playing around with the sample site!
   • Change some markup a template file and the site will regenerate automatically
   • Try adding a new field to an existing content type then add it to the corresponding GraphQL query and template

Deploying your templates

When you are done tinkering and are ready to put your site online follow these steps:

1. Configure a Static Site in the TakeShape webapp.
   1. Open your project in TakeShape
   2. Click on "Static Sites" from the project dropdown menu.
   3. Click the "NEW STATIC SITE" button.
   4. Give your site a name such as "Production" or "Staging"
   5. Select your "Provider" and enter in the appropriate credentials.
2. Use the CLI to point your local development folder to the static site you just created.
   • npm run init - Follow the command prompts
3. Use the CLI to deploy your templates!
   • npx takeshape deploy - Deploy your site to TS!
4. Once the templates are deployed TakeShape will generate HTML and push your website to the configured provider
   • Check your bucket/webserver to see the fruits of your labor
   • Additional publishes can be triggered using the "Deploy " in the project menu

Project Structure

Files and directories in this repo are designed to get you up and running with TS in seconds. After you poke around a bit you'll see how easy it is to lay in your own build processes and tools. One of the core concepts of TS is to do just enough and provide just enough structure to make your life easier without getting in your way. We want you to be creative.

Directories

• src - Holds template files (configurable by templatePath) that will be processed by the TS static site generator or files and directories that will be handled by your own build process.
• static - (configurable in tsg.yml) Anything inside the static folder will be copied over into the build folder. If you have a build process to generate files like scss into css or combine js files they should output into the static folder or in subdirectories of the static folder.

TS Configuration

• .graphqlrc - Generated by init. Reference to the TS endpoint
• .takeshaperc - Generated by init. Details to connect to a specific project on the TS platform
• tsg.yml - Configuration options to build your project including paths to relevant directories, routes and data contexts

tsg.yml Configuration Options

templatePath: src/templates   #Sets the path to look for templates
staticPath: static            #TS deploys this directory. All of your JS, CSS need to end up here. Files like robots.txt, humans.txt and other files that do not need processing should live here.
buildPath: build              #Temporary build directory

 locale: en-us #defaut
 dates:
   tz: America/New_York #default
   format: LLL #default

context:                      #Global context available to all routes.
  assets: ../../static/assets/manifest.json
  [KEY]: [VALUE]
  ...

routes:                       #Routes tell TS which template to join with which context (graphql query) and the format of the resulting directory structure to generate
  homepage:
    path: /
    template: pages/homepage.html
    context: data/homepage.graphql
...

Templating

TS uses the Nunjucks templating language. You can find detailed documentation on the Nunjucks site: (https://mozilla.github.io/nunjucks/templating.html

TS specific Nunjucks Filters

• route(routeName: String)

  {{ post | route('posts') }}
  

  Returns a relative path to a piece of content as defined by the routes in tsg.yml. The input Object must have the necessary fields specified in the route path in order to construct the path properly.
• md

  {{ markdown | md }}
  

  Markdown to safe HTML using the CommonMark spec http://commonmark.org/
• numberFormat(format: String)

  {{ numberField | numberformat(',.2r') }}
  # grouped thousands with two significant digits, 4200 -> "4,200"
  

  Returns a number formatted according to the the format specifier string https://github.com/d3/d3-format
• code(language: String)

  {{ codeField | code('javascript') }}
  

  Uses prism.js to return an HTML representation of the highlighted code. Takes an optional language string. You will need to manually include the corresponding CSS in your project.
• image(params: Object)

  {{ imageField | image({w: 320, h: 240, q: 90, crop: 'faces'}) }}
  

  Returns an imgix ready url. Takes an object of keys and values for any imgix filter https://docs.imgix.com/apis/url
• date(format: String|Object)

  {{ date | date('MMM Do YYYY') }}
  {{ date | date({format: 'MMM Do YYYY', tz: 'America/Los_Angeles') }}
  {{ date | date({format: 'LLL', tz: 'America/Los_Angeles', locale: 'fr') }}
  

  Formats dates using moment.js. format can be either a format string or an object where you can specify a format and override the default timezone and locale (configured in tsg.yml).

GraphQL tips

If you're using JetBrains we recommend using the JS GraphQL plugin. This plugin allows for real time validation of your queries against the schema you define in TS though modeling

Reach out

If we can make your life easier we want to hear from you at support@takeshape.io