7.4 KiB
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 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.
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.
| 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)