Merge pull request #618 from pupil-labs/update-social-media-share-docs

add docs for updating social media preview links

README.md

@@ -1,11 +1,13 @@
 # Pupil Docs
+
 Pupil Docs website built with Vuepress.
 
 User and Developer Docs for [Pupil](https://github.com/pupil-labs/pupil).
 
 View the docs at [docs.pupil-labs.com](https://docs.pupil-labs.com)
 
 ## Contributing
+
 We welcome all contributions! To edit content:
 
 1. Fork this repository
@@ -16,11 +18,13 @@ We welcome all contributions! To edit content:
 1. Make a Pull Request
 
 ## Download
+
 For this project, we use Yarn for dependency management.
 
 Download and install [Yarn](https://yarnpkg.com/en/docs/install).
 
 ## Install
+
 Fork or clone this repository and run the following command to install the dependencies.
 
 ```bash
@@ -30,24 +34,31 @@ yarn
 ## Development
 
 To generate markdown files from Jupyter notebooks install nbconvert via
+
 ```
 pip install nbconvert
 ```
+
 and run the following command
+
 ```
 jupyter-nbconvert --to markdown **/*.ipynb --ExtractOutputPreprocessor.enabled=False
 ```
+
 on a Windows machine, you can achieve the same output by running the following command using PowerShell
-``` 
+
+```
 ls *.ipynb -Recurse | foreach{jupyter-nbconvert --to markdown $_ --ExtractOutputPreprocessor.enabled=False}
 ```
 
 Start local development with:
+
 ```bash
 yarn dev
 ```
 
 To generate static assets, run:
+
 ```basg
 yarn build
 ```
@@ -68,28 +79,29 @@ is_notebook: true
 ```markdown
 .
 ├── src
-│   ├── .vuepress
-│   │   ├── components
-│   │   ├── theme
-│   │   │   └── layouts
-│   │   ├── public (static)
-│   │   │   └── imgs/videos
-│   │   ├── config.js
-│   │   └── enhanceApp.js
-│   │
-│   ├── media (processed by webpack)
-│   │   └── imgs/videos
-│   │
-│   ├── core
-│   │   ├── user-guide.md
-│   │   └── README.md
-│   │
-│   └── README.md
+│ ├── .vuepress
+│ │ ├── components
+│ │ ├── theme
+│ │ │ └── layouts
+│ │ ├── public (static)
+│ │ │ └── imgs/videos
+│ │ ├── config.js
+│ │ └── enhanceApp.js
+│ │
+│ ├── media (processed by webpack)
+│ │ └── imgs/videos
+│ │
+│ ├── core
+│ │ ├── user-guide.md
+│ │ └── README.md
+│ │
+│ └── README.md
 │
 └── package.json
 ```
 
 ## Page routing
+
 In the root dir are where all the page routes are located.
 
 | Relative Path     | Page Routing |
@@ -105,19 +117,65 @@ permalink: /core/software/pupil-capture
 ---
 ```
 
+## Preview social media share
+
+The social media preview is generated by Vuepress via frontmatter of each `.md` file. Anyone working on docs can just update the frontmatter to update the preview.
+
+This is an example frontmatter config for showing a preview image, using Twitter (X) Summary Card. You can also use Youtube thumbnail URL for the preview image. A valid URL is required to show a preview image.
+
+```
+---
+title: Title of the current page.
+description: Description of the current page.
+permalink: /<url>
+meta:
+  - name: twitter:card
+    content: summary_large_image
+  - name: twitter:image
+    content: "https://i.ytimg.com/vi/cuvWqVOAc5M/maxresdefault.jpg"
+  - property: og:image
+    content: "https://i.ytimg.com/vi/cuvWqVOAc5M/maxresdefault.jpg"
+tags: [Neon]
+---
+```
+
+If you would like to preview Youtube video, you can use Twitter (X) Player Card and update the meta config like so:
+
+Just update the Youtube video id in the example
+
+```
+meta:
+  - name: twitter:card
+    content: player
+  - name: twitter:image
+    content: "https://i.ytimg.com/vi/cuvWqVOAc5M/maxresdefault.jpg"
+  - name: twitter:player
+    content: "https://www.youtube.com/embed/cuvWqVOAc5M"
+  - name: twitter:width
+    content: "1280"
+  - name: twitter:height
+    content: "720"
+  - property: og:image
+    content: "https://i.ytimg.com/vi/cuvWqVOAc5M/maxresdefault.jpg"
+```
+
+Read more: https://vuepress.vuejs.org/guide/frontmatter.html#alternative-frontmatter-formats
 
 ## Images & media
+
 - `src/media` - This is where most people will be adding images, videos, etc. For all assets that will be used in .md files.
 - `src/.vuepress/public` - Primarily for those who are developing the theme. For assets that are used in .vue files.
 
 #### Relative URLs
+
 All Markdown files are compiled into Vue components and processed by webpack, so you can and should prefer referencing any asset using relative URLs:
 
 ```markdown
 ![An image](./image.png)
 ```
 
 #### Public files
+
 Sometimes you may need to provide static assets that are not directly referenced in any of your Markdown or theme components - for example, favicons and PWA icons. In such cases, you can put them inside `src/.vuepress/public` and they will be copied to the root of the generated directory.
 
 #### Asset formats
@@ -130,16 +188,19 @@ Sometimes you may need to provide static assets that are not directly referenced
 Note - `webm` and `webp` will be implemented in future iterations.
 
 ## Style Guide
+
 We aim for the docs to be concise and readable.
 
 All content is written in Markdown. If you're new to Markdown see [this guide](https://guides.github.com/features/mastering-markdown/ "Github - Mastering Markdown"). HTML markup is also parsed but discouraged unless absolutely needed.
 
 ### Table of contents
+
 All H1, H2, H3 headers will be automatically added to the table of contents.
 
 Please only use H1-H4 headings. If you find yourself needing more nesting, you should re-think your content. _Don't use H5_.
 
 ### Code blocks
+
 VuePress uses Prism to highlight language syntax in Markdown code blocks, using coloured text.
 Prism supports a wide variety of programming languages.
 All you need to do is append a valid language alias to the beginning backticks for the code block:
@@ -151,24 +212,29 @@ print("welcome to pupil docs")
 ````
 
 ### Custom container
+
 You can add highlighted notes with a little HTML embedded in your markdown document:
 
 #### Text only
+
 ```markdown
 ::: tip
 Text.
 :::
 ```
 
 #### Text with title
+
 ```markdown
 ::: warning Title
 Text.
 :::
 ```
 
 #### Text with icon
+
 `v-icon` is a vuetify tag, so you could change the color property and also replace the icon by changing the `error_outline` to any Material Icons.
+
 ```markdown
 ::: danger
 <v-icon large color="warning">error_outline</v-icon>
@@ -203,6 +269,7 @@ Wrap the icon and text in the same block.
 ``` -->
 
 ### Youtube videos
+
 Use Youtube component to quickly add videos to markdown files.
 
 Just copy and paste the unique video ID to the src prop of the component like so.
@@ -215,8 +282,8 @@ https://www.youtube.com/watch?v=HGMjJLnK2_4
 <Youtube src="HGMjJLnK2_4"/>
 ```
 
-
 ### Videos
+
 Use Videos component to quickly add local videos to markdown files.
 
 Just add the relative path of the video to the src prop of the component like so.
@@ -228,7 +295,6 @@ Note that you need to use `require` in order for Webpack to correctly resolve th
 
 The default video type is `video/mp4` which is automatically added but in case you are using a different type of video, just update the type prop.
 
-
 ```md
 <Videos :src="require(`../../media/core/videos/worldcam-focus.webm`)" type="video/webm">
 ```