Merge pull request #16 from yorickshan/docs-site

ci: generate docs site

.github/workflows/deploy.yml

@@ -0,0 +1,64 @@
+# Sample workflow for building and deploying a VitePress site to GitHub Pages
+#
+name: Deploy VitePress site to Pages
+
+on:
+  # Runs on pushes targeting the `main` branch. Change this to `master` if you're
+  # using the `master` branch as the default branch.
+  push:
+    branches: [main]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Not needed if lastUpdated is not enabled
+      # - uses: pnpm/action-setup@v3 # Uncomment this if you're using pnpm
+      # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm # or pnpm / yarn
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Install dependencies
+        run: npm ci # or pnpm install / yarn install / bun install
+      - name: Build with VitePress
+        run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -18,3 +18,5 @@ tests/reftests.js
 *.log
 .rpt2_cache
 .history
+docs/.vitepress/dist
+docs/.vitepress/cache

README.md

@@ -15,7 +15,7 @@ html2canvas-pro has several advantages over html2canvas, including:
 - support color function ```oklab()```
 - support color function ```oklch()```
 - Support object-fit of ```<img/>```
-- Fixed some known [issues](./CHANGELOG.md)
+- Fixed some [issues](./CHANGELOG.md)
 
 ## Installation
 

docs/.vitepress/config.mts

@@ -0,0 +1,33 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "html2canvas-pro",
+  description: "Next generation JavaScript Screenshots Tooling",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Guide', link: '/getting-started' }
+    ],
+
+    sidebar: [
+      {
+        text: 'Guide',
+        items: [
+          { text: 'About', link: '/about' },
+          { text: 'Why html2canvas-pro', link: '/why' },
+          { text: 'Getting Started', link: '/getting-started' },
+          { text: 'Configuration', link: '/configuration' },
+          { text: 'Features', link: '/features' },
+          { text: 'Proxy', link: '/proxy' },
+          { text: 'Faq', link: '/faq' }
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/yorickshan/html2canvas-pro' }
+    ]
+  }
+})

docs/documentation.md → docs/about.md

@@ -1,9 +1,4 @@
----
-title: "About"
-description: "Learn about html2canvas, how it works and some of its limitations"
-nextUrl: "./getting-started"
-nextTitle: "Getting Started"
----
+# About
 
 Before you get started with the script, there are a few things that are good to know regarding the 
 script and some of its limitations.
@@ -27,7 +22,7 @@ CSS properties which do not work. For a full list of supported CSS properties, c
 ## Limitations
 All the images that the script uses need to reside under the [same origin](http://en.wikipedia.org/wiki/Same_origin_policy) 
 for it to be able to read them without the assistance of a [proxy](./proxy). Similarly, if you have other `canvas` 
-elements on the page, which have been tainted with cross-origin content, they will become dirty and no longer readable by html2canvas.
+elements on the page, which have been tainted with cross-origin content, they will become dirty and no longer readable by html2canvas-pro.
 
 The script doesn't render plugin content such as Flash or Java applets.
 

docs/configuration.md

@@ -1,11 +1,4 @@
----
-title: "Options"
-description: "Explore the different configuration options available for html2canvas"
-previousUrl: "./getting-started"
-previousTitle: "Getting Started"
-nextUrl: "./features"
-nextTitle: "Features"
----
+# Configuration
 
 These are all of the available configuration options.
 
@@ -20,7 +13,7 @@ These are all of the available configuration options.
 | logging | `true` | Enable logging for debug purposes
 | onclone | `null` | Callback function which is called when the Document has been cloned for rendering, can be used to modify the contents that will be rendered without affecting the original source document.
 | proxy | `null` | Url to the [proxy](./proxy) which is to be used for loading cross-origin images. If left empty, cross-origin images won't be loaded.
-| removeContainer | `true` | Whether to cleanup the cloned DOM elements html2canvas creates temporarily
+| removeContainer | `true` | Whether to cleanup the cloned DOM elements html2canvas-pro creates temporarily
 | scale | `window.devicePixelRatio` | The scale to use for rendering. Defaults to the browsers device pixel ratio.
 | useCORS | `false` | Whether to attempt to load images from a server using CORS
 | width | `Element` width | The width of the `canvas`
@@ -32,4 +25,4 @@ These are all of the available configuration options.
 | windowWidth | `Window.innerWidth` | Window width to use when rendering `Element`, which may affect things like Media queries
 | windowHeight | `Window.innerHeight` | Window height to use when rendering `Element`, which may affect things like Media queries
 
-If you wish to exclude certain `Element`s from getting rendered, you can add a `data-html2canvas-ignore` attribute to those elements and html2canvas will exclude them from the rendering.
+If you wish to exclude certain `Element`s from getting rendered, you can add a `data-html2canvas-ignore` attribute to those elements and html2canvas-pro will exclude them from the rendering.

docs/faq.md

@@ -1,12 +1,9 @@
----
-title: "FAQ"
-description: "Explore Frequently Asked Questions regarding html2canvas"
----
+# FAQ
 
 ## Why aren't my images rendered?
-html2canvas does not get around content policy restrictions set by your browser. Drawing images that reside outside of 
+html2canvas-pro does not get around content policy restrictions set by your browser. Drawing images that reside outside of 
 the [origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) of the current page [taint the 
-canvas](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image#What_is_a_tainted_canvas) that they are drawn upon. If the canvas gets tainted, it cannot be read anymore. As such, html2canvas implements 
+canvas](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image#What_is_a_tainted_canvas) that they are drawn upon. If the canvas gets tainted, it cannot be read anymore. As such, html2canvas-pro implements 
 methods to check whether an image would taint the canvas before applying it. If you have set the `allowTaint` 
 [option](./configuration) to `false`, it will not draw the image.
 
@@ -15,6 +12,8 @@ If you wish to load images that reside outside of your pages origin, you can use
 ## Why is the produced canvas empty or cuts off half way through?
 Make sure that `canvas` element doesn't hit [browser limitations](https://stackoverflow.com/questions/6081483/maximum-size-of-a-canvas-element) for the `canvas` size or use the window configuration options to set a custom window size based on the `canvas` element:
 ```
+import html2canvas from 'html2canvas-pro';
+
 await html2canvas(element, {
     windowWidth: element.scrollWidth,
     windowHeight: element.scrollHeight
@@ -38,11 +37,11 @@ The window limitations vary by browser, operating system and system hardware.
 > The maximum size for a canvas element is 3 megapixels for devices with less than 256 MB RAM and 5 megapixels for devices with greater or equal than 256 MB RAM
 
 ## Why doesn't CSS property X render correctly or only partially?
-As each CSS property needs to be manually coded to render correctly, html2canvas will *never* have full CSS support. 
+As each CSS property needs to be manually coded to render correctly, html2canvas-pro will *never* have full CSS support. 
 The library tries to support the most [commonly used CSS properties](./features) to the extent that it can. If some CSS property 
 is missing or incomplete and you feel that it should be part of the library, create test cases for it and a new issue for it.
 
-## How do I get html2canvas to work in a browser extension?
-You shouldn't use html2canvas in a browser extension. Most browsers have native support for capturing screenshots from 
+## How do I get html2canvas-pro to work in a browser extension?
+You shouldn't use html2canvas-pro in a browser extension. Most browsers have native support for capturing screenshots from 
 tabs within extensions. Relevant information for [Chrome](https://developer.chrome.com/extensions/tabs#method-captureVisibleTab) and 
 [Firefox](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D#drawWindow()).

docs/features.md

@@ -1,7 +1,4 @@
----
-title: "Features"
-description: "Discover the different features supported by html2canvas"
----
+# Features
 
 Below is a list of all the supported CSS properties and values.
 

docs/getting-started.md

@@ -1,15 +1,8 @@
----
-title: "Getting Started"
-description: "Learn how to start using html2canvas"
-previousUrl: "./documentation"
-previousTitle: "About"
-nextUrl: "./configuration"
-nextTitle: "Configuration"
----
+# Getting Started
 
 ## Installing
 
-You can install `html2canvas` through npm or [download a built release](https://github.com/niklasvh/html2canvas/releases).
+You can install `html2canvas-pro` through npm or [download a built release](https://github.com/yorickshan/html2canvas-pro/releases).
 
 ### npm
 
@@ -21,7 +14,7 @@ import html2canvas from 'html2canvas-pro';
 
 ## Usage
 
-To render an `element` with html2canvas with some (optional) [options](/configuration/), simply call `html2canvas(element, options);`
+To render an `element` with html2canvas with some (optional) [options](./configuration), simply call `html2canvas(element, options);`
 
 ```javascript
 html2canvas(document.body).then(function(canvas) {

docs/index.md

@@ -0,0 +1,18 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "html2canvas-pro"
+  text: "Screenshots with JavaScript"
+  tagline: A fork of niklasvh/html2canvas with some fixes and new features.
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /getting-started
+    - theme: alt
+      text: Why html2canvas-pro?
+      link: /why
+    - theme: alt
+      text: View on Github
+      link: https://github.com/yorickshan/html2canvas-pro

docs/proxy.md

@@ -1,9 +1,6 @@
----
-title: "Proxy"
-description: "Browse different proxies available for supporting CORS content"
----
+# Proxy
 
-html2canvas does not get around content policy restrictions set by your browser. Drawing images that reside outside of 
+html2canvas-pro does not get around content policy restrictions set by your browser. Drawing images that reside outside of 
 the origin of the current page taint the canvas that they are drawn upon. If the canvas gets tainted, 
 it cannot be read anymore. If you wish to load images that reside outside of your pages origin, you can use a proxy to load the images.
 

docs/why.md

@@ -0,0 +1,10 @@
+# Why html2canvas-pro
+
+html2canvas-pro has several advantages over html2canvas, including:
+- support color function ```color()``` (including relative colors)
+- support color function ```lab()```
+- support color function ```lch()```
+- support color function ```oklab()```
+- support color function ```oklch()```
+- Support object-fit of ```<img/>```
+- Fixed some [issues](https://github.com/yorickshan/html2canvas-pro/blob/main/CHANGELOG.md)