mirror of
https://github.com/google/pebble.git
synced 2025-06-01 16:03:11 +00:00
Import the pebble dev site into devsite/
This commit is contained in:
Katharine Berry
parent
3b92768480
commit
527858cf4c
1359 changed files with 265431 additions and 0 deletions
12
devsite/docs/development.md
Normal file
12
devsite/docs/development.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
# Pebble Developer Site · Development Guide
|
||||
|
||||
## Handlebars Templates
|
||||
|
||||
In order to reduce the size of the JS of the site, we are now pre-compiling
|
||||
the Handlebars templates and just using the runtime Handlebars library.
|
||||
|
||||
If you change, add or remove from the templates, you just recompile them
|
||||
into the file at `/source/assets/js/templates.js`.
|
||||
|
||||
There is a bash script at `/scripts/update-templates.sh` that you can use to
|
||||
generate this file.
|
||||
84
devsite/docs/environment.md
Normal file
84
devsite/docs/environment.md
Normal file
|
|
@ -0,0 +1,84 @@
|
|||
# Environment Variables
|
||||
|
||||
The following environment variables are used in the generation of the site.
|
||||
|
||||
## URL
|
||||
|
||||
This overrides the `url` configuration parameter of Jeyll. Set this to the root
|
||||
of where the site will be hosted.
|
||||
|
||||
```
|
||||
URL=http://developer.pebble.com
|
||||
```
|
||||
|
||||
## HTTPS_URL
|
||||
|
||||
This overrides the `https_url` configuration parameter of Jeyll. Set this to
|
||||
the secure root of where the site will be hosted.
|
||||
|
||||
```
|
||||
HTTPS_URL=https://developer.pebble.com
|
||||
```
|
||||
|
||||
## PORT
|
||||
|
||||
The port on which the Jekyll server will listen. If you don't set this it will
|
||||
default to port `4000`.
|
||||
|
||||
```
|
||||
PORT=8000
|
||||
```
|
||||
|
||||
## ASSET_PATH
|
||||
|
||||
This sets the `asset_path` configuration variable, which tells the site where
|
||||
the assets are to be found.
|
||||
|
||||
During development and testing, this can be set to the relative URL of the
|
||||
assets folder inside the main site.
|
||||
|
||||
For production, this should be set to the CDN where the assets will be uploaded.
|
||||
|
||||
*Note:* As of 8th January 2014, the production version of the site still used
|
||||
local assets and not a CDN.
|
||||
|
||||
```
|
||||
ASSET_PATH=assets/
|
||||
```
|
||||
|
||||
## EXTERNAL_SERVER
|
||||
|
||||
This sets the `external_server` configuration variable, which tells the site the
|
||||
location of the external server used for events, community blog and contact.
|
||||
|
||||
```
|
||||
EXTERNAL_SERVER=https://developer-api.getpebble.com
|
||||
```
|
||||
|
||||
## DOCS_URL
|
||||
|
||||
The URL of the server on which the documentation sources are being built.
|
||||
|
||||
The production and staging values are private, so if you do not work for Pebble
|
||||
you will have to omit it from the environment (or `.env` file). Sorry
|
||||
|
||||
## ALGOLIA_*
|
||||
|
||||
The site search is powered by [Algolia](https://algolia.com). There are four
|
||||
environment variables that are required to turn on indexing at build time and
|
||||
also correctly setup the client JS for searching. The production and staging
|
||||
values can be found on our Algolia account.
|
||||
|
||||
If you do not work for Pebble, or don't care about testing the indexing, then
|
||||
omit these values from the environment (or `.env` file) to disable Algolia.
|
||||
|
||||
The `ALGOLIA_PREFIX` value is extremely important. Make sure you set it if you
|
||||
are enabling Algolia support on the site, and check that it matches the scoped
|
||||
search key.
|
||||
|
||||
```
|
||||
ALGOLIA_APP_ID=
|
||||
ALGOLIA_API_KEY=
|
||||
ALGOLIA_SEARCH_KEY=
|
||||
ALGOLIA_PREFIX=
|
||||
```
|
||||
305
devsite/docs/markdown.md
Normal file
305
devsite/docs/markdown.md
Normal file
|
|
@ -0,0 +1,305 @@
|
|||
# Writing Markdown
|
||||
|
||||
If you are writing anything in Markdown for the Pebble Developer site, you
|
||||
should read this guide to learn about some of the rules and enhancements that
|
||||
the site has, beyond those of "standard Markdown".
|
||||
|
||||
## Styleguide
|
||||
|
||||
### 80 character lines
|
||||
|
||||
To keep your Markdown files readable and easy to review, please break all lines
|
||||
at 80 characters.
|
||||
|
||||
*NOTE:* The line breaking does not affect the HTML output, this is purely to
|
||||
keep the source files readable and reviewable.
|
||||
|
||||
### Headers
|
||||
|
||||
Use the `#`, `##` etc syntax for headers, and include a space after the hashes
|
||||
and before the header text.
|
||||
|
||||
```
|
||||
## Write Headers Like This
|
||||
|
||||
##Don't Write Them Like This
|
||||
|
||||
And Definitely Don't Do This
|
||||
=======
|
||||
```
|
||||
|
||||
You should also generally avoid using the top level header (`#`) because the
|
||||
page that is displaying the content will be using the document title in a \<h1\>
|
||||
tag automatically.
|
||||
|
||||
#### Table of Contents
|
||||
|
||||
If enabled, the table of contents for the document will include all headers on
|
||||
the page.
|
||||
|
||||
You can enable/disable table of contents generation for a specific page in the
|
||||
YAML metadata:
|
||||
|
||||
```
|
||||
generate_toc: true
|
||||
```
|
||||
|
||||
#### Anchors
|
||||
|
||||
All headers automatically have anchors attached to them, so you can easily link
|
||||
to sections of the page. The ID for the header will be the slugized header text.
|
||||
|
||||
For example, `## Install Your App` will become `#install-your-app`.
|
||||
|
||||
### Blockcode
|
||||
|
||||
Use triple backticks for block code, and
|
||||
[specify the language](http://pygments.org/languages/) to ensure the syntax is
|
||||
highlighted correctly.
|
||||
|
||||
```js
|
||||
var foo = 'bar';
|
||||
```
|
||||
|
||||
|
||||
#### Click to Copy
|
||||
|
||||
By default, all code blocks will include the Click to Copy button in the
|
||||
top right corner. If you want to disable it, prepend the language with `nc^`.
|
||||
|
||||
```nc^text
|
||||
This is not for copying!
|
||||
```
|
||||
|
||||
### Images
|
||||
|
||||
In blog posts and guides, images will be block elements that are centered on
|
||||
the page. *Plan accordingly.*
|
||||
|
||||
#### Size
|
||||
|
||||
You can control the width (and optionally height) of images using the following
|
||||
syntax:
|
||||
|
||||
```
|
||||
|
||||
|
||||
```
|
||||
|
||||
### HTML
|
||||
|
||||
Do not use HTML unless you **absolutely** have to. It is almost always better to
|
||||
use Markdown so that we can more easily maintain a consistent style across the
|
||||
site.
|
||||
|
||||
## Additional Syntax
|
||||
|
||||
### Buttons
|
||||
|
||||
To convert any link into a button simply append a `>` onto the end of the text.
|
||||
|
||||
```
|
||||
[Button Text >](http://google.com/)
|
||||
```
|
||||
|
||||
You can optionally pass extra button classes after the `>` to modify the style
|
||||
of the button.
|
||||
|
||||
```
|
||||
[Wide Orange Button >{wide,fg-orange}](http://google.com)
|
||||
```
|
||||
|
||||
The available classes are:
|
||||
|
||||
* wide
|
||||
* small
|
||||
* center
|
||||
* fg-COLOR
|
||||
* bg-COLOR
|
||||
|
||||
*Where COLOR is any one of the [available colors](README.md#colors).*
|
||||
|
||||
### Link Data
|
||||
|
||||
To add additional data attributes to links (useful for outbound tracking),
|
||||
append a `>` to the end of the link title, and format the content as below.
|
||||
|
||||
```
|
||||
[Link Text](http://google.com "Link Title >{track-event:click,track-name:google}")
|
||||
```
|
||||
|
||||
This will create a link with the attributes `data-track-event="click"` and
|
||||
`data-track-name="google"`.
|
||||
|
||||
### SDK Documentation Links
|
||||
|
||||
If you wish to link to a section of the SDK documentation, you can do so using
|
||||
double backticks. This can either be done to enhance existing inline code
|
||||
or in the text of a link.
|
||||
|
||||
```
|
||||
This will link to the ``window_create`` documentation.
|
||||
|
||||
You should check out the page on [Events](``event services``)
|
||||
```
|
||||
|
||||
### Pebble Screenshots
|
||||
|
||||
If you want to provide a watch screenshot and have it displayed in a Pebble
|
||||
wrapper, you should upload the 144x168 image and use the following syntax.
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
You can pick from any of the following screenshot wrappers:
|
||||
|
||||
* pebble-screenshot--black
|
||||
* pebble-screenshot--white
|
||||
* pebble-screenshot--red
|
||||
* pebble-screenshot--gray
|
||||
* pebble-screenshot--orange
|
||||
* pebble-screenshot--steel-black
|
||||
* pebble-screenshot--steel-stainless
|
||||
* pebble-screenshot--snowy-black
|
||||
* pebble-screenshot--snowy-red
|
||||
* pebble-screenshot--snowy-white
|
||||
* pebble-screenshot--time-round-black-20
|
||||
* pebble-screenshot--time-round-red-14
|
||||
|
||||
The following screenshot classes exist, but the accompanying images are not
|
||||
currently available. They will be aliased to black-20 or red-14 as size
|
||||
dictates:
|
||||
|
||||
* pebble-screenshot--time-round-rosegold-14
|
||||
* pebble-screenshot--time-round-silver-14
|
||||
* pebble-screenshot--time-round-silver-20
|
||||
|
||||
> Please match the wrapper to the screenshot where possible. For example, do not
|
||||
use an original Pebble wrapper with a color screenshot.
|
||||
|
||||
#### Screenshot Viewer
|
||||
|
||||
If you want to show matching screenshots across multiple platforms, you should use the new
|
||||
`screenshot_viewer` tag.
|
||||
|
||||
Here is an example of it in use:
|
||||
|
||||
```
|
||||
{% screenshot_viewer %}
|
||||
{
|
||||
"image": "/images/guides/pebble-apps/display-animations/submenu.png",
|
||||
"platforms": [
|
||||
{ "hw": "basalt", "wrapper": "time-red" },
|
||||
{ "hw": "chalk", "wrapper": "time-round-red-14" }
|
||||
]
|
||||
}
|
||||
{% endscreenshot_viewer %}
|
||||
```
|
||||
|
||||
The URL to the image gets the hardware platform insert into it, so in order to make
|
||||
the above example work, you should have two files with the following names:
|
||||
|
||||
```
|
||||
/source/assets/images/guides/pebble-apps/display-animations/submenu~basalt.png
|
||||
/source/assets/images/guides/pebble-apps/display-animations/submenu~chalk.png
|
||||
```
|
||||
|
||||
### Alerts
|
||||
|
||||
Some information requires more prominent formatting than standard block notes.
|
||||
Use the `alert` Liquid tag for this purpose. Both 'notice' (purple) and
|
||||
'important' (dark red) are supported for appropriate levels of highlighting.
|
||||
Some examples are below:
|
||||
|
||||
```
|
||||
{% alert important %}
|
||||
PebbleKit JS and PebbleKit Android/iOS may **not** be used in conjunction.
|
||||
{% endalert %}
|
||||
```
|
||||
|
||||
```
|
||||
{% alert notice %}
|
||||
This API is currently in the beta stage, and may be changed before final
|
||||
release.
|
||||
{% endalert %}
|
||||
```
|
||||
|
||||
### SDK Platform Specific Paragraphs
|
||||
|
||||
On pages that have the SDK Platform choice system, you can tag paragraphs as
|
||||
being only relevant for CloudPebble or local SDK users. Text, code snippets,
|
||||
images, and other markdown are all supported.
|
||||
|
||||
First, add `platform_choice: true` to the page YAML metadata.
|
||||
|
||||
Specify platform-specific sections of markdown using the `platform` Liquid tag:
|
||||
|
||||
```
|
||||
{% platform local %}
|
||||
Add the resource to your project in `package.json`.
|
||||
{% endplatform %}
|
||||
|
||||
{% platform cloudpebble %}
|
||||
Add the resource to your project by clicking 'Add New' next to 'Resources' in
|
||||
the project sidebar.
|
||||
{% endplatform %}
|
||||
```
|
||||
|
||||
### Formatting
|
||||
|
||||
The following additional text formatting syntax is supported.
|
||||
|
||||
#### Strikethrough
|
||||
|
||||
```
|
||||
This is some ~~terribly bad~~ amazingly good code.
|
||||
```
|
||||
|
||||
#### Highlight
|
||||
|
||||
```
|
||||
CloudPebble is ==extremely== good.
|
||||
```
|
||||
|
||||
#### Tables
|
||||
|
||||
Tables are supported with the
|
||||
[PHP Markdown syntax](https://michelf.ca/projects/php-markdown/extra/#table).
|
||||
|
||||
```
|
||||
| First Header | Second Header |
|
||||
| ------------- | ------------- |
|
||||
| Content Cell | Content Cell |
|
||||
| Content Cell | Content Cell |
|
||||
```
|
||||
|
||||
### Emoji
|
||||
|
||||
You can use emoji in your text by using the colon syntax.
|
||||
|
||||
```
|
||||
If you're a beginner Pebble developer, you should use :cloud:Pebble
|
||||
```
|
||||
|
||||
### Embedded Content
|
||||
|
||||
#### YouTube
|
||||
|
||||
To embed a YouTube video or playlist, use the standard link syntax with EMBED
|
||||
as the link title.
|
||||
|
||||
```
|
||||
You should check out this video on developing Pebble apps:
|
||||
[EMBED](https://www.youtube.com/watch?v=LU_hPBhgjGQ)
|
||||
```
|
||||
|
||||
#### Gist
|
||||
|
||||
To embed a GitHub Gist, use the standard link syntax with EMBED as the link
|
||||
title.
|
||||
|
||||
```
|
||||
Here is the Gist code.
|
||||
[EMBED](https://gist.github.com/JaviSoto/5405969)
|
||||
```
|
||||
16
devsite/docs/troubleshooting.md
Normal file
16
devsite/docs/troubleshooting.md
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
# Troubleshooting
|
||||
|
||||
This page contains fixes to known problems encountered from building the
|
||||
developer site, and how they were fixed. This may help you if you have
|
||||
the same problems.
|
||||
|
||||
## Nokogiri
|
||||
|
||||
**Error**
|
||||
|
||||
> An error occurred while installing nokogiri (1.6.7.2), and Bundler cannot continue.
|
||||
> Make sure that `gem install nokogiri -v '1.6.7.2'` succeeds before bundling.
|
||||
|
||||
**Solution**
|
||||
|
||||
`gem install nokogiri -- --use-system-libraries`
|
||||
Loading…
Add table
Add a link
Reference in a new issue