📖 Fix docs (ampproject#31420)

* fix docs

* remove fixed sizes

* review

* remove segment

* remove fixed sizes from imgs to make table take full width

spec/amp-story-player.md

@@ -140,23 +140,28 @@ player.load();
 **Parameters**
 
 - number: the story in the player to which you want to move, relative to the current story.
+- number (optional): the page of the story to which you want to move, relative to the current page.
 
 If the player is currently on the third story out of five stories:
 
 - `player.go(1)` will go forward one story to the fourth story
 - `player.go(-1)` will go backward one story to the second story
-- If no value is passed or if delta equals 0, current story will persist and no action will be taken.
+- `player.go(-1, 1)` will go backward one story and navigate one page backwards
+- `player.go(0, 5)` will stay in the current story and navigate 5 pages forward
 
 #### show
 
 **Parameters**
 
-- string: the URL of the story to show.
+- string or null: the URL of the story to show.
+- string (optional): the ID attribute of the page element.
 
 Will change the current story being displayed by the player.
 
 ```javascript
-player.show(url);
+player.show('cool-story.html'); // Will display cool-story.html
+player.show('cool-story.html', 'page-4'); // Will display cool-story.html and switch to page-4
+player.show(null, 'page-4'); // Stay on current story and switch to page-4
 ```
 
 #### add
@@ -419,7 +424,7 @@ Since by default the close button will be placed to the end, all we have to do i
 </amp-story-player>
       </pre>
     </td>
-    <td><img width="360" height="600" src="https://github.com/ampproject/amphtml/blob/master/src/amp-story-player/img/lightbox-close-button.png?raw=true"></td>
+    <td><img src="https://github.com/ampproject/amphtml/blob/master/src/amp-story-player/img/lightbox-close-button.png?raw=true"></td>
   </tr>
 </table>
 
@@ -503,6 +508,18 @@ player.addEventListener('navigation', (event) => {
 })
 ```
 
+#### storyNavigation
+
+Fired when the story inside the player changes to a new page. It provides the `pageId` and `progress` of the story. The progress is the completion percentage of the story represented as a number between 0 and 1.
+
+```javascript
+player.addEventListener('storyNavigation', (event) => {
+  console.log('User navigated from one page to the other.');
+  console.log('Current page id:' event.pageId); // page-2
+  console.log('Story progress:' event.progress); // Number from 0 to 1.
+})
+```
+
 ### noNextStory
 
 Dispatched when there is no next story. Note that this will not be dispatched when using [Circular wrapping](#Circular-wrapping).

src/amp-story-player/README.md

@@ -10,12 +10,12 @@
 
 ## Summary
 
-The player is fully available and the functionalities here (unless otherwise specified) are ready to use. The goal of this issue is to polish documentation, provide more examples of the player, and showcase new functionalities. To learn how to try out the new features (marked in (**Beta**)), refer to the [FAQs](<#FAQs-(please-feel-free-to-reach-out-with-other-questions-&-thoughts)>).
+The player is fully available and the functionalities here (unless otherwise specified) are ready to use. The goal of this issue is to polish documentation, provide more examples of the player, and showcase new functionalities. To learn how to try out the new features (marked in (**Beta**)), refer to the [FAQs](#faqs-please-feel-free-to-reach-out-with-other-questions--thoughts).
 
 This update contains guidance on using the Web Story Player to support:
 
 - [Navigating between stories](#Navigating-between-stories)
-- [Integrating Web Stories into your website (entrypoints)](<#Integrating-web-stories-into-your-website-(entrypoints)>)
+- [Integrating Web Stories into your website (entrypoints)](#integrating-web-stories-into-your-website-entrypoints)
 - [Programmatically fetching more stories](#Programmatically-fetching-more-stories)
 - [Circular wrapping](#Circular-wrapping)
 - [Customizing position & visibility of story UI controls](#Customizing-position-&-visibility-of-story-UI-controls)
@@ -26,7 +26,7 @@ Beyond this, you’ll also find:
 
 - [Additional use case demos](#Additional-use-case-demos)
 - [Additional explorations and roadmap](#Additional-explorations-and-roadmap)
-- [FAQs](<#FAQs-(please-feel-free-to-reach-out-with-other-questions-&-thoughts)>)
+- [FAQs](#faqs-please-feel-free-to-reach-out-with-other-questions--thoughts)
 
 ## Player setup
 
@@ -84,15 +84,15 @@ There are many ways in which you can use the player on your own surfaces. Below
 <tbody>
   <tr>
     <td><strong>Carousel with circle avatars</strong> <br>In this codepen, we provide an example of how to create a carousel entry point and how to link it to your player. <br> <a href="https://codepen.io/maenrique/pen/wvWjNYr" target="_blank" rel="noopener noreferrer">https://codepen.io/maenrique/pen/wvWjNYr</a><br><br><strong>Demo</strong>  <br>This demo showcases a more complex implementation with a horizontally scrollable carousel and the player being opened in a lightbox. <br><a href="https://web-player-cards-carousel.web.app/examples/amp-story/player-entry-point-circular.html" target="_blank" rel="noopener noreferrer">https://web-player-cards-carousel.web.app/examples/amp-story/player-entry-point-circular.html</a><br></td>
-    <td><img width="360" height="642" src="https://github.com/ampproject/amphtml/blob/master/src/amp-story-player/img/carousel-circuclar-entry-point.png?raw=true"></td>
+    <td><img src="https://github.com/ampproject/amphtml/blob/master/src/amp-story-player/img/carousel-circuclar-entry-point.png?raw=true"></td>
   </tr>
   <tr>
     <td><strong>Carousel with cards</strong><br>In this codepen, we provide an example of how to create a simple card carousel entry point and how to link it to your player.<br><a href="https://codepen.io/maenrique/pen/MWeGxqY" target="_blank" rel="noopener noreferrer">https://codepen.io/maenrique/pen/MWeGxqY</a><br><br><strong>Demo</strong> <br>This demo showcases a more complex implementation with a horizontally scrollable carousel and the player being opened in a lightbox. <br> <a href="https://web-player-cards-carousel.web.app/examples/amp-story/player-entry-point-cards.html" target="_blank" rel="noopener noreferrer">https://web-player-cards-carousel.web.app/examples/amp-story/player-entry-point-cards.html</a><br><br></td>
-    <td><img width="360" height="642" src="https://github.com/ampproject/amphtml/blob/master/src/amp-story-player/img/carousel-cards-entry-point.png?raw=true"></td>
+    <td><img src="https://github.com/ampproject/amphtml/blob/master/src/amp-story-player/img/carousel-cards-entry-point.png?raw=true"></td>
   </tr>
   <tr>
     <td>Embedding directly into some text<br>The simplest way to use the player is to directly embed the player in your platform.<br><a href="https://web-player-cards-carousel.web.app/examples/amp-story/player-blog.html" target="_blank" rel="noopener noreferrer">Demo</a><br></td>
-    <td><img width="360" height="409" src="https://github.com/ampproject/amphtml/blob/master/src/amp-story-player/img/embed-in-blog.png?raw=true"></td>
+    <td><img src="https://github.com/ampproject/amphtml/blob/master/src/amp-story-player/img/embed-in-blog.png?raw=true"></td>
   </tr>
 </tbody>
 </table>
@@ -303,7 +303,7 @@ Since by default the close button will be placed to the end, all we have to do i
 </amp-story-player>
       </pre>
     </td>
-    <td><img width="360" height="600" src="https://github.com/ampproject/amphtml/blob/master/src/amp-story-player/img/lightbox-close-button.png?raw=true"></td>
+    <td><img src="https://github.com/ampproject/amphtml/blob/master/src/amp-story-player/img/lightbox-close-button.png?raw=true"></td>
   </tr>
 </table>