diff --git a/README.md b/README.md index 4911618f9..7592d9a6a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # Pupil Docs + Pupil Docs website built with Vuepress. User and Developer Docs for [Pupil](https://github.com/pupil-labs/pupil). @@ -6,6 +7,7 @@ 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,12 +117,57 @@ 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: / +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 @@ -118,6 +175,7 @@ All Markdown files are compiled into Vue components and processed by webpack, so ``` #### 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,9 +212,11 @@ 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. @@ -161,6 +224,7 @@ Text. ``` #### Text with title + ```markdown ::: warning Title Text. @@ -168,7 +232,9 @@ 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 error_outline @@ -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 ``` - ### 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 ```