Move documentation into Docusaurus

docs-website/.gitignore

@@ -0,0 +1,20 @@
+# 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*

docs-website/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ 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
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs-website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs-website/blog/2022-03-27-ransack-3.0.0.md

@@ -0,0 +1,16 @@
+---
+slug: ransack-3-0-0
+title: Ransack 3.0.0
+authors:
+  name: Sean Carroll
+  title: Ransack Core Team
+tags: [ransack, release]
+---
+
+Ransack has been a part of many Rubyists toolboxes for years and 3.0.0 is a major release. We have a number of new features and one breaking change. As part of 3.0.0, we decided to launch this documentation website, merging in the Wiki and the content from the README.
+
+With 3.0.0 we are hoping to re-energise the community, we need help on closing out old issues, refactoring the codebase and even some design work.
+
+I also wanted to let you know that Ernie Miller (creator of Ransack) has decided to leave the project completely, he has this message for the community:
+
+> While my own personal development efforts have been spent elsewhere as of late, I'm keenly aware of how many people still depend on some of the software I originally wrote all those years ago. That's why I'm grateful to be able to step away from the ActiveRecord Hackery organization (and, specifically, maintenance of Ransack) without impacting those users. I'm thankful that Sean, David, Greg, and others will continue to support users, and wish them the best as they move forward without me!

docs-website/docs/getting-started/advanced-mode.md

@@ -0,0 +1,39 @@
+### Advanced Mode
+
+"Advanced" searches Rails's nested attributes functionality in order to
+generate complex queries with nested AND/OR groupings, etc. This takes a bit
+more work but can generate some pretty cool search interfaces that put a lot of
+power in the hands of your users. A notable drawback with these searches is
+that the increased size of the parameter string will typically force you to use
+the HTTP POST method instead of GET. :(
+
+This means you'll need to tweak your routes...
+
+```ruby
+resources :people do
+  collection do
+    match 'search' => 'people#search', via: [:get, :post], as: :search
+  end
+end
+```
+
+... and add another controller action ...
+
+```ruby
+def search
+  index
+  render :index
+end
+```
+
+... and update your `search_form_for` line in the view ...
+
+```erb
+<%= search_form_for @q, url: search_people_path,
+                        html: { method: :post } do |f| %>
+```
+
+Once you've done so, you can make use of the helpers in [Ransack::Helpers::FormBuilder](lib/ransack/helpers/form_builder.rb) to
+construct much more complex search forms, such as the one on the
+[demo app](http://ransack-demo.herokuapp.com/users/advanced_search)
+(source code [here](https://github.com/activerecord-hackery/ransack_demo)).

docs-website/docs/getting-started/configuration.md

@@ -0,0 +1,37 @@
+Ransack may be easily configured. The best place to put configuration is in an initializer file at `config/initializers/ransack.rb`, containing code such as:
+
+```ruby
+Ransack.configure do |config|
+
+  # Change default search parameter key name.
+  # Default key name is :q
+  config.search_key = :query
+
+  # Raise errors if a query contains an unknown predicate or attribute.
+  # Default is true (do not raise error on unknown conditions).
+  config.ignore_unknown_conditions = false
+
+  # Globally display sort links without the order indicator arrow.
+  # Default is false (sort order indicators are displayed).
+  # This can also be configured individually in each sort link (see the README).
+  config.hide_sort_order_indicators = true
+
+end
+```
+
+## Custom search parameter key name
+
+Sometimes there are situations when the default search parameter name cannot be used, for instance,
+if there are two searches on one page. Another name may be set using the `search_key` option in the `ransack` or `search` methods in the controller, and in the `@search_form_for` method in the view.
+
+```ruby
+# in the controller:
+@search = Log.ransack(params[:log_search], search_key: :log_search)
+# or
+@search = Log.search(params[:log_search], search_key: :log_search)
+```
+```erb
+in the view:
+<%= f.search_form_for @search, as: :log_search %>
+<%= sort_link(@search) %>
+```

docs-website/docs/getting-started/i18n.md

@@ -0,0 +1,48 @@
+### I18n
+
+Ransack translation files are available in
+[Ransack::Locale](lib/ransack/locale). You may also be interested in one of the
+many translations for Ransack available at
+http://www.localeapp.com/projects/2999.
+
+Predicate and attribute translations in forms may be specified as follows (see
+the translation files in [Ransack::Locale](lib/ransack/locale) for more examples):
+
+locales/en.yml:
+```yml
+en:
+  ransack:
+    asc: ascending
+    desc: descending
+    predicates:
+      cont: contains
+      not_cont: not contains
+      start: starts with
+      end: ends with
+      gt: greater than
+      lt: less than
+    models:
+      person: Passanger
+    attributes:
+      person:
+        name: Full Name
+      article:
+        title: Article Title
+        body: Main Content
+```
+
+Attribute names may also be changed globally, or under `activerecord`:
+
+```yml
+en:
+  attributes:
+    model_name:
+      model_field1: field name1
+      model_field2: field name2
+  activerecord:
+    attributes:
+      namespace/article:
+        title: AR Namespaced Title
+      namespace_article:
+        title: Old Ransack Namespaced Title
+```

docs-website/docs/getting-started/search-matches.md

@@ -0,0 +1,71 @@
+### Search Matchers
+
+List of all possible predicates
+
+
+| Predicate | Description | Notes |
+| ------------- | ------------- |-------- |
+| `*_eq`  | equal  | |
+| `*_not_eq` | not equal | |
+| `*_matches` | matches with `LIKE` | e.g. `q[email_matches]=%@gmail.com`|
+| `*_does_not_match` | does not match with `LIKE` | |
+| `*_matches_any` | Matches any | |
+| `*_matches_all` | Matches all  | |
+| `*_does_not_match_any` | Does not match any | |
+| `*_does_not_match_all` | Does not match all | |
+| `*_lt` | less than | |
+| `*_lteq` | less than or equal | |
+| `*_gt` | greater than | |
+| `*_gteq` | greater than or equal | |
+| `*_present` | not null and not empty | Only compatible with string columns. Example: `q[name_present]=1` (SQL: `col is not null AND col != ''`) |
+| `*_blank` | is null or empty. | (SQL: `col is null OR col = ''`) |
+| `*_null` | is null | |
+| `*_not_null` | is not null | |
+| `*_in` | match any values in array | e.g. `q[name_in][]=Alice&q[name_in][]=Bob` |
+| `*_not_in` | match none of values in array | |
+| `*_lt_any` | Less than any |  SQL: `col < value1 OR col < value2` |
+| `*_lteq_any` | Less than or equal to any | |
+| `*_gt_any` | Greater than any | |
+| `*_gteq_any` | Greater than or equal to any | |
+| `*_lt_all` | Less than all | SQL: `col < value1 AND col < value2` |
+| `*_lteq_all` | Less than or equal to all | |
+| `*_gt_all` | Greater than all | |
+| `*_gteq_all` | Greater than or equal to all | |
+| `*_not_eq_all` | none of values in a set | |
+| `*_start` | Starts with | SQL: `col LIKE 'value%'` |
+| `*_not_start` | Does not start with | |
+| `*_start_any` | Starts with any of | |
+| `*_start_all` | Starts with all of | |
+| `*_not_start_any` | Does not start with any of | |
+| `*_not_start_all` | Does not start with all of | |
+| `*_end` | Ends with | SQL: `col LIKE '%value'` |
+| `*_not_end` | Does not end with | |
+| `*_end_any` | Ends with any of | |
+| `*_end_all` | Ends with all of | |
+| `*_not_end_any` | | |
+| `*_not_end_all` | | |
+| `*_cont` | Contains value | uses `LIKE` |
+| `*_cont_any` | Contains any of | |
+| `*_cont_all` | Contains all of | |
+| `*_not_cont` | Does not contain |
+| `*_not_cont_any` | Does not contain any of | |
+| `*_not_cont_all` | Does not contain all of | |
+| `*_i_cont` | Contains value with case insensitive | uses `ILIKE` |
+| `*_i_cont_any` | Contains any of values with case insensitive | |
+| `*_i_cont_all` | Contains all of values with case insensitive | |
+| `*_not_i_cont` | Does not contain with case insensitive |
+| `*_not_i_cont_any` | Does not contain any of values with case insensitive | |
+| `*_not_i_cont_all` | Does not contain all of values with case insensitive | |
+| `*_true` | is true | |
+| `*_false` | is false | |
+
+
+(See full list: https://github.com/activerecord-hackery/ransack/blob/master/lib/ransack/locale/en.yml#L15 and [wiki](https://github.com/activerecord-hackery/ransack/wiki/Basic-Searching))
+
+### Using Ransackers to add custom search functions via Arel
+
+The main premise behind Ransack is to provide access to
+**Arel predicate methods**. Ransack provides special methods, called
+_ransackers_, for creating additional search functions via Arel. More
+information about `ransacker` methods can be found [here in the wiki](https://github.com/activerecord-hackery/ransack/wiki/Using-Ransackers).
+Feel free to contribute working `ransacker` code examples to the wiki!