GithubHelp home page GithubHelp logo
docs

formio / docs Goto Github PK

View Code? Open in 1sVSCode Editor NEW

This project forked from sendgrid/docs

0.0 5.0 2.0 134.47 MB

The code generating SendGrid's documentation. Please feel free to make pull requests, if there's anything you feel we could do better!

Home Page: http://sendgrid.com/docs/

License: MIT License

Ruby 18.17% Shell 0.04% JavaScript 20.25% Perl 16.39% HTML 36.35% GCC Machine Description 0.01% CSS 8.80%

docs's Introduction

SendGrid Documentation

Build Status Dependency Status

This site is based on Octopress, which is in turn based on Jekyll, with a dash of Twitter Bootstrap added.

The develop branch is continuously deployed to a preview site. View dev site

The master branch is continuously deployed to production.

Please, feel free to make any contributions you feel will make SendGrid Documentation better.

Submit all pull requests to the develop branch

Local Setup

  • Clone the repo.
  • npm install to install build tools.
  • bower install to install client-side dependencies (jQuery, bootstrap)
  • bundle install to install required rubygems.
  • Copy _config.sample.yml and name it _config.yml
  • Set your root (if you're running locally it'll just be /) in _config.yml
  • bundle exec rake preview
  • Browse to localhost:4000

Important Things to Know

  • The source files are in /source, and the generated files will be created in /public. They get overwritten or wiped out when the site is rebuilt.

  • To rebuild the site: rake generate

Config your local

The config is defined in _config.yml.

The only config variables you should need to know about are root, which is the root from which all links are calculated, and the folder_weights hash, which specifies the order that the folders should be displayed in the nav tree. Higher weights mean higher display priority (higher in the tree). You can also specify icons for folders with the folder_icons hash.

There's also a version number in the config.

Vagrant Setup

  • Clone the repo.

  • Bring up development environment with Vagrant

      $ vagrant up
    
  • Browse to http://localhost:4000

Testing

	$ vagrant ssh
	$ cd docs && bin/test

Important Things to Know

  • The source files are in /source, and the generated files will be created in /public. They get overwritten or wiped out when the site is rebuilt.

  • To rebuild the site: rake generate

Config

The config is defined in _config.yml.

The only config variables you should need to know about are root, which is the root from which all links are calculated, and the folder_weights hash, which specifies the order that the folders should be displayed in the nav tree. Higher weights mean higher display priority (higher in the tree). You can also specify icons for folders with the folder_icons hash.

There's also a version number in the config.

The Nav Tree

The nav tree is generated by the plugin site_navigation.rb. It is essentially a recursive traversal of all the folders and pages in the Source folder that generates a hierarchical tree, sorted by folder weight and page weight.

Breadcrumbs are generated by the breadcrumbs.rb plugin.

Pages

You can write pages in markdown, HTML, or HAML. They all get converted to HTML when the site is generated.

Pages have a block of YAML at the top that sets a few options. They are pretty self explanatory; here's an example

---
layout: page
weight: 0
title: Docs Home
icon: icon-home
showTitle: false
navigation:
  show: true
---

Weights are same as the folder weights - the higher numbers move higher up the tree. Icons are based on the CSS icon class names from Twitter Bootstrap. showTitle and navigation["show"] both default to true if not specified.

SEO

Various fields pertinent to SEO can be controlled through the YAML frontmatter. Here's an example:

---
seo:
  title: Really Great Documentation - SendGrid Documentation | SendGrid
  override: true
  description: This is some really great documentation! I hope you like it!
  canonical: http://sendgrid.com/docs/really-great-docs
---

By default <title> tags follow the template {Page Title} {Site Title}. However the page title can be changed for the purpose of the tag by using seo["title"]. seo["override"] will override the entire template, instead making the title tage {seo["title"]}. description and canonical change their respective tags.

Custom Liquid Tags

There are some custom plugins (look in the plugins folder) that define new liquid blocks for use in pages.

Anchors

You can create anchor tags that will have named anchors generated for them automatically with links on hover. The parameter is the wrapping element to use.

{% anchor h2 %}
Some Anchor Text
{% endanchor %}

Info blocks

Similarly you can create info and warning blocks:

{% info %}
Some info for a breakout block.
{% endinfo %}

{% warning %}
...And a warning breakout.
{% endwarning %}

API Examples

If you are working on API reference docs, you can generate XML and JSON nav tabs and the corresponding example calls and responses like so:

{% apiexample identifier GET http://some.endpoint.url var1=stuff&var2=junk %}
  {% response json %}
{ "foo": "bar" }
  {% endresponse %}

  {% response xml %}
<foo>bar</foo>
  {% endresponse %}
{% endapiexample %}

The parameters for the apiexample block are: unique identifier, HTTP method, the url (excluding .json or .xml extension), and the data payload in querystring format.

JS and CSS, etc

JavaScript and CSS are minified and combined. The files to be packaged and their orders are specified in _includes/head.html and CssMinify.yml. Preprocessing and options can be specified via _plugins/jekyll_asset_pipeline.rb.

docs's People

Contributors

brandonmwest avatar eschallock avatar imathis avatar nquinlan avatar Zaftula avatar jacobmovingfwd avatar fhemberger avatar katieporter avatar Reformant avatar eddiezane avatar thinkingserious avatar johnvajda avatar leormanelis avatar elliejohnson avatar bhammerquist avatar stewartjarod avatar martyndavies avatar vladiacobsendgrid avatar motdotla avatar tbrenner avatar ws avatar SuePom avatar amustoe avatar ryanlittleton avatar stephenswhite avatar scottkawai avatar awwa avatar danielamihalache avatar trotha01 avatar rbin avatar

Watchers

Travis Tidwell avatar Randall Knutson avatar James Cloos avatar  avatar Denise Kay avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.