🔄 synced file(s) with sidebase/nuxt-pdf

content/6.nuxt-pdf/1.getting-started/1.index.md

@@ -1,22 +1,53 @@
 ---
-description: "Introduction to `nuxt-pdf` and its features for exporting html pages to pdf."
+description: "Introduction to `nuxt-pdf`."
 ---
 
 # Introduction
 
-`nuxt-pdf` is a Nuxt 3 wrapper around [jsPDF](https://github.com/parallax/jsPDF), a package that allows you to export PDF documents from your web apps.
+`nuxt-pdf` is an open source Nuxt 3 PDF toolkit, that allows you to easily render PDFs application or server side.
 
 ::list{type="success"}
-- Adds built in Nuxt 3 support to export components to a PDF Document
-- Works with native Nuxt 3 refs, allowing you to keep your clean Nuxt 3 code free from any external package
+- Client side exporting of Vue components to HTML
+- Server side rendering of complex PDFs
+- Simple encryption of your PDFs, by allowing you to set a password and permissions
+- Editable forms inside your PDFs
+- Pre-build components to quickly develop your PDF
+- documentation, recipes and example code to get you started
 ::
 
-After installing the module you will be able to access the function like so:
-```ts
-// file: ~/app.vue
-import { exportToPDF } from '#imports'
+::callout
+#summary
+Show me the code!
 
-await exportToPDF('my-pdf-file.pdf', HTMLElement)
-```
+#content
+Visit the [quick start](/nuxt-pdf/getting-started/quick-start) page to see code examples.
+::
+
+## Which method is right for me?
+
+Generating PDFs on the client or through the server fundamentally change how the PDF is compiled and created. We try and ensure that our feature set matches both methods equally, however there are a few method-specific features. These are listed below.
+
+|                                                     | Application Side | Server Side |
+|-----------------------------------------------------|------------------|-------------|
+| **Features**                                        |                  |             |
+| Convert Vue components to PDFs                      | ✅                | ❌           |
+| Add Encryption to your PDFs                         | ✅                | ✅           |
+| Define Layouts for your PDFs                        | ❌                | ✅           |
+| Use your Tailwind Styles                            | ✅                | ❌           |
+| Use pre-build components to create your PDF         | ❌                | ✅           |
+| Define your default PDF options in `nuxt.config.ts` | ❌                | ✅           |
+
+One factor that this table does not take into account is the reliablity and consistency, that server side generated PDFs will add to your application. Generating a PDF from HTML code, may result in different appearences, based on the browser, screen size and other settings on an individuals PC, limiting the control you have over the finished product. Rendering your PDFs on the server side, will allow you to control the output to a mich higher degree.
+
+### Use cases
+
+#### Application side
+
+- You need to quickly develop your PDF integration
+- You already have Vue components developed, that can be reused to generate the PDFs
+- You are not concerned about minor layout shifts and differences between browsers
+
+#### Server side
 
-See more in the [Quick Start section](/nuxt-pdf/getting-started/quick-start).
+- You require a higher degree of control over the output
+- You are developing complex PDFs that may require large amounts of data, you do not want to directly expose to a users client

content/6.nuxt-pdf/1.getting-started/3.quick-start.md

@@ -12,9 +12,20 @@ export default defineNuxtConfig({
 })
 ```
 
-That's it! You can now begin exporting Nuxt 3 components to PDF. For example:
+## Examples
+
+That's it! You can now begin creating PDFs in your Nuxt 3 application!
+
+### Application side
+
+You can export Vue components to HTML through our composables. You can learn more about using `nuxt-pdf` in the application side [here](/nuxt-pdf/application-side).
 
 ```vue
+// file: ~/components/PDF.vue
+<script setup lang="ts">
+const pdfSection = ref<HTMLElement | null>(null)
+</script>
+
 <template>
   <div>
     <div ref="pdfSection">
@@ -25,16 +36,21 @@ That's it! You can now begin exporting Nuxt 3 components to PDF. For example:
     </button>
   </div>
 </template>
+```
 
-<script setup lang="ts">
-import { ref } from 'vue'
-import { exportToPDF } from '#imports'
+### Server side
 
-const pdfSection = ref<HTMLElement | null>(null)
-</script>
-```
+Or use our server side code based approch to define your design! You can learn more about using `nuxt-pdf` on the server side [here](/nuxt-pdf/server-side).
 
-We offer two separate options parameters, that allow you to customize your pdf export. 
+```ts
+// file: ~/server/api/pdf/my-pdf.vue
+import { createPDF, streamReturnPDF } from '#pdf'
+
+export default eventHandler(async (event) => {
+  const pdf = createPDF()
+  pdf.text('Welcome to NuxtPDF!')
+  pdf.end()
 
-- The `documentOptions`, allow you to customize the general layout of your document. You can find the options [here](http://raw.githack.com/MrRio/jsPDF/master/docs/jsPDF.html).
-- The `htmlOptions`, allow you to customize the conversion of your HTML to a canvas. You can find the options [here](http://raw.githack.com/MrRio/jsPDF/master/docs/module-html.html#~html).
+  return streamReturnPDF(event, pdf)
+})
+```

content/6.nuxt-pdf/1.getting-started/4.getting-help.md

@@ -0,0 +1,15 @@
+---
+description: "How to get help when using `nuxt-pdf` in your Vue / Nuxt 3 application."
+---
+
+# Getting Help
+
+At some point, you may find that there's an issue you need some help with.
+
+But don't worry! We're a friendly community of developers and we'd love to help. Concretely this means to:
+- Checkout the docs (page that you are currently viewing),
+- Search open issues and discussions: https://github.com/sidebase/nuxt-pdf/issues
+- Hop on Discord to ask us directly: https://discord.gg/VzABbVsqAc,
+- Open an issue to file a bug, ask for an enhancement or get an answer to a question: https://github.com/sidebase/nuxt-pdf/issues/new/choose
+
+We aim to follow the getting-help standards of the nuxt-project as described here and ask you to do the same when opening an issue or pinging us for help: https://nuxt.com/docs/community/getting-help#getting-help.

content/6.nuxt-pdf/2.application-side/4.composables.md

@@ -0,0 +1,75 @@
+# Composables
+
+`nuxt-pdf` exposes multiple composables, that you can access to easily create pdfs through vue code.
+
+## Options
+
+Both of our composables, accept 2 seperate configuration options.
+- The `documentOptions`, allow you to customize the general layout of your document. You can find the options [here](http://raw.githack.com/MrRio/jsPDF/master/docs/jsPDF.html).
+- The `htmlOptions`, allow you to customize the conversion of your HTML to a canvas. You can find the options [here](http://raw.githack.com/MrRio/jsPDF/master/docs/module-html.html#~html).
+
+
+## `exportToPDF`
+
+`exportToPDF` allows you to usea native vue ref, to target either a native HTML element, or a Vue component, which will then be converted into a PDF.
+
+The composable accepts 4 parameters:
+- The fileName
+- The component you wish to convert
+- The documentOptions
+- The HTMLOptions.
+
+To learn more about the options, please refer [here](#options)
+
+```vue
+<script setup lang="ts">
+const pdfSection = ref<HTMLElement | null>(null)
+
+const DOCUMENT_OPTIONS = {} // See all options: http://raw.githack.com/MrRio/jsPDF/master/docs/jsPDF.html
+const HTML_OPTIONS = {} // See all options: http://raw.githack.com/MrRio/jsPDF/master/docs/module-html.html#~html
+
+const export = () => {
+  await exportToPDF('FILE_NAME.pdf', pdfSection, DOCUMENT_OPTIONS, HTML_OPTIONS)
+}
+</script>
+
+<template>
+  <div ref="pdfSection">
+    <h1>Hello world!</h1>
+  </div>
+</template>
+```
+
+### Tips & Tricks
+
+- Ensure that the section you want to export has a fixed width, to ensure the layout does not shift when exporting
+- Setting a fixed width and height, to match your document size, will lead to better results
+- Use the `scale` option in the document section, to slightly increase or decrease the size of the rendered html
+- Optimize your HTML to reduce the PDF file size
+
+## `htmlToPDF`
+
+`htmlToPdf` allows you to pass an HTML string and format it into a PDF. This can allow you to futhur customize the behaviour of how the module interacts with your UI.
+
+```ts
+import { htmlToPdf } from '#imports'
+
+const openInWindow = async (HTMLElement: HTMLElement) => {
+  const pdf = await htmlToPdf(HTMLElement,
+    undefined,
+    {
+      html2canvas: {
+        scale: 0.7,
+        useCORS: true
+      }
+    })
+  const totalPages = pdf.getNumberOfPages()
+  const pdfHeight = pdf.getPageHeight()
+  await pdf.html('<b>I am a custom pdf!!!</b>', {
+    x: 20,
+    y: (pdfHeight - 50) * totalPages // place in the bottom
+  })
+  const blob = pdf.output('blob')
+  window.open(URL.createObjectURL(blob), '_blank')
+}
+```

content/6.nuxt-pdf/2.application-side/_dir.yml

@@ -0,0 +1,2 @@
+title: Application-Side
+icon: heroicons-outline:computer-desktop

content/6.nuxt-pdf/3.server-side/1.index.md

@@ -0,0 +1,3 @@
+# Introduction
+
+This page is a work in progress. Please have a look at the playground until we get around to these!

content/6.nuxt-pdf/3.server-side/_dir.yml

@@ -0,0 +1,2 @@
+title: Server-Side
+icon: heroicons-outline:server