layerware · csummers · Jan 4, 2022 · Jan 4, 2022
diff --git a/docs/hugsql.org/.gitignore b/docs/hugsql.org/.gitignore
@@ -1,3 +1,20 @@
-_site
-publish
-.jekyll-cache/
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/docs/hugsql.org/README.md b/docs/hugsql.org/README.md
@@ -1,5 +1,25 @@
-# HugSQL source for documentation site
+# hugsql.org docs
 
-Go to [hugsql.org](http://hugsql.org)
+Built with [Docusaurus 2](https://docusaurus.io/).
 
-Site is generated with [jekyll](https://jekyllrb.com/).
+### Installation
+
+```shell
+$ yarn
+```
+
+### Local Development
+
+```shell
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```shell
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
diff --git a/docs/hugsql.org/babel.config.js b/docs/hugsql.org/babel.config.js
@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
diff --git a/docs/hugsql.org/blog/2019-05-28-first-blog-post.md b/docs/hugsql.org/blog/2019-05-28-first-blog-post.md
@@ -0,0 +1,12 @@
+---
+slug: first-blog-post
+title: First Blog Post
+authors:
+  name: Gao Wei
+  title: Docusaurus Core Team
+  url: https://github.com/wgao19
+  image_url: https://github.com/wgao19.png
+tags: [hola, docusaurus]
+---
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
diff --git a/docs/hugsql.org/blog/2019-05-29-long-blog-post.md b/docs/hugsql.org/blog/2019-05-29-long-blog-post.md
@@ -0,0 +1,44 @@
+---
+slug: long-blog-post
+title: Long Blog Post
+authors: endi
+tags: [hello, docusaurus]
+---
+
+This is the summary of a very long blog post,
+
+Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.
+
+<!--truncate-->
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
diff --git a/docs/hugsql.org/blog/2021-08-01-mdx-blog-post.mdx b/docs/hugsql.org/blog/2021-08-01-mdx-blog-post.mdx
@@ -0,0 +1,20 @@
+---
+slug: mdx-blog-post
+title: MDX Blog Post
+authors: [slorber]
+tags: [docusaurus]
+---
+
+Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/markdown-features), such as [MDX](https://mdxjs.com/).
+
+:::tip
+
+Use the power of React to create interactive blog posts.
+
+```js
+<button onClick={() => alert('button clicked!')}>Click me!</button>
+```
+
+<button onClick={() => alert('button clicked!')}>Click me!</button>
+
+:::
diff --git a/docs/hugsql.org/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg b/docs/hugsql.org/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg
diff --git a/docs/hugsql.org/blog/2021-08-26-welcome/index.md b/docs/hugsql.org/blog/2021-08-26-welcome/index.md
@@ -0,0 +1,25 @@
+---
+slug: welcome
+title: Welcome
+authors: [slorber, yangshun]
+tags: [facebook, hello, docusaurus]
+---
+
+[Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog).
+
+Simply add Markdown files (or folders) to the `blog` directory.
+
+Regular blog authors can be added to `authors.yml`.
+
+The blog post date can be extracted from filenames, such as:
+
+- `2019-05-30-welcome.md`
+- `2019-05-30-welcome/index.md`
+
+A blog post folder can be convenient to co-locate blog post images:
+
+![Docusaurus Plushie](./docusaurus-plushie-banner.jpeg)
+
+The blog supports tags as well!
+
+**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config.
diff --git a/docs/hugsql.org/blog/authors.yml b/docs/hugsql.org/blog/authors.yml
@@ -0,0 +1,17 @@
+endi:
+  name: Endilie Yacop Sucipto
+  title: Maintainer of Docusaurus
+  url: https://github.com/endiliey
+  image_url: https://github.com/endiliey.png
+
+yangshun:
+  name: Yangshun Tay
+  title: Front End Engineer @ Facebook
+  url: https://github.com/yangshun
+  image_url: https://github.com/yangshun.png
+
+slorber:
+  name: Sébastien Lorber
+  title: Docusaurus maintainer
+  url: https://sebastienlorber.com
+  image_url: https://github.com/slorber.png
diff --git a/docs/hugsql.org/docs/faq/_category_.json b/docs/hugsql.org/docs/faq/_category_.json
@@ -0,0 +1,4 @@
+{
+    "label": "Frequently Asked Questions",
+    "position": 6
+  }
diff --git a/docs/hugsql.org/docs/faq/comparison-with-yesql.md b/docs/hugsql.org/docs/faq/comparison-with-yesql.md
@@ -0,0 +1,22 @@
+---
+sidebar_position: 0
+---
+
+# Comparison with Yesql
+
+Yesql is a Clojure library written by Kris Jenkins. It has a similar take on using SQL that HugSQL embraces whole-heartedly. Yesql is the spiritual predecessor to HugSQL, and HugSQL would not exist were it not for this great library.
+
+**So why build a similar library?**
+
+> A project of mine with somewhat complex SQL required me to generate dynamically-named tables and views with variable columns, and I found myself having to revert back to string concatenation for building up my SQL. I realized I needed something similar to Yesql, but with support for different types of parameter placeholders: namely, SQL Identifiers and SQL Keywords. This was the seed that grew into HugSQL, and the two libraries have quite a few differences now. --Curtis Summers
+
+Differences between Yesql and HugSQL:
+
+- Yesql is coupled to `clojure.java.jdbc`. HugSQL has protocol-based adapters to allow multiple database backend libraries and ships with support for `clojure.java.jdbc`, `next.jdbc`, and `clojure.jdbc`. This functionality has enabled [multiple adapters from the community](/hugsql-adapters/community-adapters). See [HugSQL Adapters](/hugsql-adapters) for more information.
+- Yesql only supports SQL Value parameters. HugSQL supports [SQL Values](/hugsql-in-detail/parameter-types/sql-value-parameters), [SQL Tuples](/hugsql-in-detail/parameter-types/sql-tuple-parameters), [SQL Identifiers](/hugsql-in-detail/parameter-types/sql-identifier-parameters), [Raw SQL Parameters](/hugsql-in-detail/parameter-types/sql-raw-parameters), and creation of your own [custom parameter types](/hugsql-in-detail/parameter-types/custom-parameter-types). See [Parameter Types](/hugsql-in-detail/parameter-types/) for more detail.
+- Yesql supports positional parameter placeholders `?` and named parameter placeholders `:id`. HugSQL only supports named parameter placeholders and there are no plans to support positional placeholders.
+- Yesql tends to favor naming conventions of the function name (`!`, and `<!` suffixes) to indicate functionality. HugSQL prefers explicit configuration in the SQL file.
+HugSQL features a `:result` configuration that indicates the expected return format (e.g., `:many` = vector of hashmaps, `:one` = hashmap). Yesql supports a similar functionality by passing the `:result-set-fn` option through to `clojure.java.jdbc/query`.
+- Yesql (as of `0.5.x`) supports setting a default database connection at the time of function definition, and optionally overriding this connection at function call time. HugSQL expects a database spec, connection, or transaction object as the first argument to your function call. However, as of version `0.4.1`, HugSQL provides `map-of-db-fns` allowing other libraries to wrap HugSQL-created functions and set a default database connection. This is precisely what the Luminus web framework's [conman](https://github.com/luminus-framework/conman) library does.
+- As of HugSQL `0.4.0`, HugSQL supports Clojure expressions and Snippets for composing SQL from smaller parts.
+- Yesql is frozen with a maintainer sought as of version `0.5.3`.
diff --git a/docs/hugsql.org/docs/faq/dsls.md b/docs/hugsql.org/docs/faq/dsls.md
@@ -0,0 +1,11 @@
+---
+sidebar_position: 2
+---
+
+# What about DSLs for SQL?
+
+Can I get the same SQL generation similar to [Honey SQL](https://github.com/seancorfield/honeysql)?
+
+HugSQL has several options for composing SQL.  See [Composability](../using-hugsql/composability/).
+
+HugSQL encourages you to think in SQL first, then sprinkle in the power of Clojure where necessary. HoneySQL starts on the Clojure side first. Both are valid workflows and a matter of developer preference and situation. It's important to realize that HugSQL and HoneySQL are not mutually exclusive: HugSQL Snippet Parameter Types `:snip` and `:snip*` can consume the sqlvec format output from HoneySQL's format function. It's the best of both worlds!
diff --git a/docs/hugsql.org/docs/faq/preventing-sql-injection.md b/docs/hugsql.org/docs/faq/preventing-sql-injection.md
@@ -0,0 +1,43 @@
+---
+sidebar_position: 3
+---
+
+# Preventing SQL Injection
+
+**How does HugSQL help protect against SQL injection?**
+
+HugSQL attempts to provide a set of tools that help protect against SQL injection where possible without taking away power from the developer. Below are a few potential SQL injection attack vectors and HugSQL's response to each:
+
+## Value Parameters
+
+[Value Parameters](/hugsql-in-detail/parameter-types/sql-value-parameters), [Value List Parameters](/hugsql-in-detail/parameter-types/sql-value-list-parameters), [Tuple Parameters](/hugsql-in-detail/parameter-types/sql-tuple-parameters), and [Tuple List Parameters](/hugsql-in-detail/parameter-types/sql-tuple-list-parameters) are all variations on SQL value parameters that convert a Clojure data type to SQL. By default, all of these parameter types defer to the underlying database library to perform [SQL parameter binding](http://martinfowler.com/articles/web-security-basics.html#ParameterBindingToTheRescue) to prevent SQL injection issues.
+
+## Identifier Parameters
+
+[Identifier Parameters](/hugsql-in-detail/parameter-types/sql-identifier-parameters) and [Identifier List Parameters\(/hugsql-in-detail/parameter-types/sql-identifier-list-parameters) support quoting and escaping of identifiers with the `:quoting option`. By default, `:quoting` is `:off`, since HugSQL makes no assumptions about your given database. This may be fine for your use case if you are not taking identifiers from user input.
+
+:::caution
+
+If you are taking identifiers from user input, you should use the `:quoting` option to prevent SQL injection! See [Identifier Parameters](/hugsql-in-detail/parameter-types/sql-identifier-parameters) for details.
+
+:::
+
+## Raw SQL Parameters
+
+:::danger
+
+[Raw SQL Parameters](/hugsql-in-detail/parameter-types/sql-raw-parameters) are exactly what they seem, and it is your responsibility to sanitize any usage of this parameter type when using user input.
+
+:::
+
+## Snippet Parameters
+
+[Snippets](/using-hugsql/composability/snippets) generate sqlvecs and Snippet Parameter Types consume sqlvecs. For snippets containing any HugSQL parameter types, the same rules as above apply. If you are consuming a snippet (or sqlvec) from your own code or another library (say, HoneySQL), then other rules might apply.
+
+## Custom Parameter Types
+
+[Custom Parameter Types](/hugsql-in-detail/parameter-types/custom-parameter-types) allow you to create your own parameter types. It is your responsibility to ensure your implementation protects against SQL injection by properly escaping your data.
+
+## Clojure Expressions
+
+[Clojure Expressions](/using-hugsql/composability/clojure-expressions) should return either a string or nil, and strings returned from expressions are parsed at runtime to support HugSQL parameters. The same rules apply for the above parameter types.
diff --git a/docs/hugsql.org/docs/faq/wacky-sql.md b/docs/hugsql.org/docs/faq/wacky-sql.md
@@ -0,0 +1,7 @@
+---
+sidebar_position: 1
+---
+
+# Does HugSQL support my wacky SQL?
+
+Yes, HugSQL's parsing strategy is to extract the parts it cares about and leave the rest of your SQL as is. If you find some SQL is not being handled properly by HugSQL, it may be a bug. [File an issue](https://github.com/layerware/hugsql/issues).