From dbbc31a3812efc6358cab0ea53ecf8fdc960424b Mon Sep 17 00:00:00 2001 From: Marcin Kulik Date: Wed, 14 Oct 2015 13:00:09 +0200 Subject: [PATCH] Update "Sharing" doc --- app/assets/stylesheets/base.sass | 3 + app/views/asciicasts/_share.html.slim | 4 +- app/views/docs/_docs_topics.html.slim | 2 +- app/views/docs/embedding.html.md | 144 +++++++++++++++----------- spec/support/feature_helpers.rb | 2 +- 5 files changed, 89 insertions(+), 66 deletions(-) diff --git a/app/assets/stylesheets/base.sass b/app/assets/stylesheets/base.sass index faae711..9b1b075 100644 --- a/app/assets/stylesheets/base.sass +++ b/app/assets/stylesheets/base.sass @@ -123,3 +123,6 @@ kbd label.radio font-weight: normal + +pre code + white-space: pre diff --git a/app/views/asciicasts/_share.html.slim b/app/views/asciicasts/_share.html.slim index ffc83b7..d12ae2b 100644 --- a/app/views/asciicasts/_share.html.slim +++ b/app/views/asciicasts/_share.html.slim @@ -44,4 +44,6 @@ p input[type="text" value=embed_script(page.asciicast) data-behavior="auto-select" readonly] p Paste the above script tag where you want the player to be displayed on your page. - p See the #{link_to 'embedding docs', docs_path(:embedding)} for additional options. + + hr + p See #{link_to 'Sharing & embedding', docs_path(:embedding)} for additional options. diff --git a/app/views/docs/_docs_topics.html.slim b/app/views/docs/_docs_topics.html.slim index 8b9fd15..0be2ec5 100644 --- a/app/views/docs/_docs_topics.html.slim +++ b/app/views/docs/_docs_topics.html.slim @@ -6,5 +6,5 @@ h2 Docs = categories.link_to 'Installation', docs_path(:installation), :installation = categories.link_to 'Usage', docs_path(:usage), :usage = categories.link_to 'Configuration file', docs_path(:config), :config - = categories.link_to 'Embedding', docs_path(:embedding), :embedding + = categories.link_to 'Sharing & embedding', docs_path(:embedding), :embedding = categories.link_to 'FAQ', docs_path(:faq), :faq diff --git a/app/views/docs/embedding.html.md b/app/views/docs/embedding.html.md index 734c969..aab387a 100644 --- a/app/views/docs/embedding.html.md +++ b/app/views/docs/embedding.html.md @@ -1,22 +1,37 @@ -<% content_for(:title, 'Embedding') %> +<% content_for(:title, 'Sharing & embedding') %> -# Embedding +# Sharing & embedding -An asciicast can be easily embedded on any HTML page. If you want to put a +You can share any recording by copying its URL and sending it to a friend or +posting it on a social network. asciinema.org supports oEmbed/Open Graph/Twitter +Card protocols, displaying a nice thumbnail where possible. + +You can also easily embedded an asciicast on any HTML page. If you want to put a recording in a blog post, project's documentation or in a conference talk -slides, you can do it by copy-pasting one of the the embed scripts. In -addition, you can share it on your favorite social network thanks to -oEmbed/Open Graph/Twitter Card support. +slides, you can do it by copy-pasting one of the the embed scripts. + +## Sharing a link + +You can get the share link for a specific asciicast by clicking on "Share" link +on asciicast page. + +Any of the options listed in "Customizing the playback" section below can be +appended to the asciicast URL as the query params, e.g.: + + https://asciinema.org/a/14?t=25&speed=2&theme=solarized-dark + +Visiting this link will start the playback at 25s and play at double speed, +using Solarized Dark terminal theme. -## Image link +## Embedding image link Embedding as an image link is useful in places where scripts are not allowed, e.g. in a project's README file. -You can get the embed snippets for a specific asciicast by clicking on "Embed" +You can get the embed snippets for a specific asciicast by clicking on "Share" link on asciicast page. -See the example below for asciicast 14. +This is how they look for asciicast 14: HTML: @@ -26,15 +41,22 @@ Markdown: [![asciicast](https://asciinema.org/a/14.png)](https://asciinema.org/a/14) -To start the playback automatically after opening linked asciicast page append -`?autoplay=1` to asciicast URL: +You can pass extra options (listed in "Customizing the playback" below) to the +linked URL as query params. For example, to start the playback automatically +when opening linked asciicast page append `?autoplay=1` to the asciicast URL in +`href` attribute: -## Player +## Embedding the player -If you're embedding on your own page or on a site which permits script tags, -you can use the full player widget: +If you're embedding on your own page or on a site which permits script tags, you +can use the full player widget. + +You can get the widget script for a specific asciicast by clicking on "Embed" +link on asciicast page. + +It looks like this: @@ -48,67 +70,42 @@ at the following markup: The player is displayed between the two paragraphs, as a `div` element with "asciicast" class. -You can get the player widget script for a specific asciicast by clicking on -"Embed" link on asciicast page. - -### Customizing the player - -The embed script supports several customization options. An option can be -applied by adding it as a -data-option-name="option-value" attribute to -the script tag. - -#### speed +The embed script supports all customization options (see the section below). An +option can be specified by adding it as a +data-option-name="value" attribute to the script +tag. -The `speed` option alters the playback speed. The default speed is 1 which -means it plays at the unaltered, original speed. - -For example, to make the playback 2 times faster than original use the -following script: +For example, to make the embedded player auto start playback when loaded and use +big font, use the following script: - + -#### size +## Customizing the playback -The `size` option alters the size of the terminal font. There are 3 available -sizes: +The player supports several options that control the behavior and look of it. +Append them to the URL (`?speed=2&theme=tango`) or set them as data attributes +on embed script (`data-speed="2" data-theme="tango"`). -* small (default) -* medium -* big +### t -For example, to make the font big use the following script: +The `t` option specifies the time at which the playback should start. The +default is `t=0` (play from the beginning). - +Accepted formats: `ss`, `mm:ss`, `hh:mm:ss`. -#### theme +NOTE: when `t` is specified then `autoplay=1` is implied. To prevent the player +from starting automatically when `t` option is set you have to explicitly set +`autoplay=0`. -The `theme` option allows overriding a theme used for the terminal. -It defaults to a theme set by the asciicast author (or to "tango" if not set -by the author). There are 3 available themes: +### autoplay -* seti -* tango -* solarized-dark -* solarized-light - -For example, to use Solarized Dark theme use the following script: - - - -#### autoplay - -The `autoplay` option allows for automatic playback start when the player -loads. Accepted values: +The `autoplay` option controls whether the playback should automatically start +when the player loads. Accepted values: * 0 / false - do not start playback automatically (default) * 1 / true - start playback automatically -For example, to make the asciicast auto play use the following script: - - - -#### loop +### loop The `loop` option allows for looping the playback. This option is usually combined with `autoplay` option. Accepted values: @@ -116,9 +113,30 @@ combined with `autoplay` option. Accepted values: * 0 / false - disable looping (default) * 1 / true - enable looping -For example, to make the asciicast play infinitely use the following script: +### speed - +The `speed` option alters the playback speed. The default speed is 1 which +means it plays at the unaltered, original speed. + +### size + +The `size` option alters the size of the terminal font. There are 3 available +sizes: + +* small (default) +* medium +* big + +### theme + +The `theme` option allows overriding a theme used for the terminal. It defaults +to a theme set by the asciicast author (or to "tango" if not set by the author). +There are 4 available themes: + +* seti +* tango +* solarized-dark +* solarized-light ## oEmbed / Open Graph / Twitter Card diff --git a/spec/support/feature_helpers.rb b/spec/support/feature_helpers.rb index 51f1246..63009e6 100644 --- a/spec/support/feature_helpers.rb +++ b/spec/support/feature_helpers.rb @@ -11,7 +11,7 @@ module Asciinema expect(page).to have_link('Getting started') expect(page).to have_link('Installation') expect(page).to have_link('Usage') - expect(page).to have_link('Embedding') + expect(page).to have_link('Sharing & embedding') expect(page).to have_link('FAQ') end