Merge pull request #51 from mshibanami/new-documentation-tool

Migrating to Docusaurus from Docsify  - part 1

build.sh

@@ -5,3 +5,10 @@ cd "$(dirname "${BASH_SOURCE:-$0}")"
 rm -rf output
 mkdir -p output/redirect-web
 cp -R docs/* output/redirect-web
+
+mkdir -p output/redirect-web/new
+cd docusaurus
+npm install
+npm run build
+
+cp -R build/* ../output/redirect-web/new

docusaurus/.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*

docusaurus/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](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.

docusaurus/babel.config.js

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

docusaurus/docs/contact-us.mdx

@@ -0,0 +1,9 @@
+# Contact Us
+
+We're here to help if you have any questions, feedback, or issues with Redirect Web. Here are the best ways to get in touch:
+
+- **[GitHub Issues](https://github.com/mshibanami/RedirectWeb/issues)**: If you encounter any bugs or want to request new features, please visit the GitHub Issues page. You can browse existing issues, submit a new issue, and track the progress of your issue.
+- **[GitHub Discussions](https://github.com/mshibanami/RedirectWeb/discussions)**: If you have any questions or want to get help from the developer or other users, please visit the GitHub Discussions page. You can start a new discussion, join existing discussions, and get help from the community.
+- **Feedback Form**: You can send us feedback through the feedback form in the Redirect Web app. This will send an email directly to the developer, so your feedback is private from other users.
+
+Thank you for using Redirect Web! We appreciate your support and feedback.

docusaurus/docs/export-or-import-rules.mdx

@@ -0,0 +1,47 @@
+# Export/Import Rules
+
+## Export Rules
+
+### macOS
+
+Click either the ellipsis button or the Share button as shown in this screenshot:
+
+![Share on macOS](/img/share-on-macos.png)
+
+You can also multi-select your rules and export them by secondary clicking (right-clicking) them on the rule-listing sidebar:
+
+![Share multiple rules on macOS](/img/multiselect-on-macos.png)
+
+In addition, you can export all the rules by the menubar > File > Export All Redirect Rules:
+
+![Menubar > File](/img/menubar-file.png)
+
+If you want to export your rules in the format compatible with [Einar Egilsson's Redirector](https://einaregilsson.com/redirector/), press the Option key (`⌥`) on the context menu or the menubar, then you'll see these:
+
+![Menubar > File (Redirector)](/img/menubar-file-redirector.png)
+
+![Context Menu (Redirector)](/img/context-menu-redirector.png)
+
+> [!WARNING]
+> Redirect Web is not fully compatible with Redirector, and vise versa. Some settings, such as "Replace Occurrences" for Capturing Group Processing, aren't exported with the Redirector's format.
+
+### iOS
+
+You can export your rules like this:
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/uQ6-SLEMlT4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+
+## Import Rules
+
+### macOS
+
+- Simply drag and drop the exported rule files to Redirect Web's window.
+- Or, you can also import them from the menubar > File > Import Redirect Rules
+
+### iOS
+
+Suppose your rule file is in the Files app. Open it on Files, tap the Share button, and then select Redirect Web:
+
+| Step 1: Tap the Share button on Files | Step 2: Select Redirect Web |
+|-|-|
+| ![Alt text](/img/files-share-ios.png) | ![Alt text](/img/share-sheet-ios.png) |

docusaurus/docs/faq.mdx

@@ -0,0 +1,55 @@
+# FAQ
+
+## Why should I allow the extension to read my information?
+
+You may see an alert like this when you set up Redirect Web:
+
+<img src={require("/img/prepareExtensionPermissionAlert@3x.png").default} alt="An permission requiring alert" width="200" />
+
+> This extension will be able to read and alter webpages and see your browsing history on this website. **This could include sensitive information, including passwords, phone numbers, and credit cards.**
+
+This extension needs your permission to observe the page navigation to redirect to wherever you want to jump, and Safari displays this alert when the extension requests the related permissions. Therefore, if you don’t allow it, this extension can't work.
+
+Since we don't collect your personal information as per **[the privacy policy](./privacy-policy)**, we recommend you **always allow** it on **every website** for your convenience.
+
+But it’s not required. You can only allow it on specific websites. 👌
+
+## Why does this extension require a new permission? \{#permission-alert-on-safari}
+
+You may see this alert in Safari after updating Redirect Web:
+
+<img src={require("/img/safari-additional-permission-alert.webp").default} alt="An alert of disabling the app" width="280" />
+
+> "Redirect Web for Safari" has been updated and is requesting additional permissions. To protect your privacy, this extension has been turned off.
+>
+> You can turn this extension on in the Extensions section of Safari Settings.
+
+This is due to the [declarativeNetRequestWithHostAccess](https://developer.apple.com/documentation/safariservices/safari_web_extensions/blocking_content_with_your_safari_web_extension) permission required by the [DNR](./rule-settings#type) type introduced in version 7. Please re-enable the extension. Sorry for the inconvenience.
+
+## Will the library's contents become paid in the future?
+
+No, it's always free. You can also find the source of all the contents [here](https://github.com/mshibanami/redirect-web/tree/main/docs/library).
+
+## One-time Purchase or Annual Subscription: Which is Best?
+
+We recommend the one-time purchase, as the price difference is only US$2.00.
+The main reason we offer the subscription is to allow you to try all the features through its free trial. Here is the expected use case:
+
+1. Subscribe the annual subscription.
+2. Immediately cancel the subscription by going to the Settings app, searching for "Subscriptions", tapping on this app, and selecting "Cancel Subscription". This lets you enjoy the free trial without any commitment.
+3. Enjoy full access to all features for 7 days.
+4. If you like the features, opt for the one-time purchase.
+
+Of course, there's nothing wrong with continuing with the annual subscription if you prefer!
+
+## Why are the toggles of my redirect rules not changing or immediately reverting back?
+
+**Edit (2023-09-01)**: We fixed this bug in version 5.0.0 for both iOS and macOS.
+
+~~It's a bug. Sorry for the inconvenience. As a workaround, try changing the sorting order of one of your redirect rules and then restoring it to the previous order.~~
+
+## Does Redirect Web inject ads or other unrelated content into websites?
+
+No, it does not inject any such content. Only code that is necessary to provide the features described in this documentation and on the app page in the App Store is injected into websites on Safari.
+
+It is possible that in the future, we may choose to show ads to users who have not unlocked the app, but these ads will only be displayed within the app or on this documentation, and not injected into websites.

docusaurus/docs/getting-started.mdx

@@ -0,0 +1,153 @@
+# Getting Started
+
+This page describes common use cases for creating redirect rules in the Redirect Web app.
+
+(You can also learn the details of rule settings on the [Rule Settings](./rule-settings) page.)
+
+
+## Case 1: Open another website
+
+Suppose you're addicted to Twitter, and you decide to meditate in Insight Timer whenever you accidentally open Twitter. Let's create a rule for that!
+
+### Step 1. Set up "Redirect From"
+
+First, you should set up the *Redirect From* section in the *Edit Rule* screen in the app. The targets are URLs starting with `https://twitter.com/`.
+
+In this case, you can specify the following pattern with the [Wildcard](rule-settings?id=wildcard) mode:
+
+```
+https://twitter.com/*
+```
+
+In the Wildcard mode, `*` means it matches anything (= zero or more characters).
+
+However, hold on. `twitter.com` was renamed to `x.com`. You can simply replace `twitter.com` with `x.com` but no one knows when the new owner will change his mind again to roll it back. Therefore, let's target both `twitter.com` and `x.com`.
+
+To do that, switch from Wildcard to [Regular Expression](rule-settings?id=regular-expression), and set this as the pattern:
+
+```
+https://(twitter|x).com/.*
+```
+
+* `(twitter|x)`: it targets both `twitter` and `x`. (`|` is called *a pipe*.)
+* `.*`: It's the same as Wildcard's `*`. More specifically, `.` means *any character* and `*` means *anything before this symbol repeated any number of times*, resulting in it matches anything.
+
+Regular Expression is a bit complicated, but once you get used to it, it will be a powerful tool. We recommend using [RegExr](https://regexr.com) as a playground to analyze how your Regular Expression pattern works.
+
+> [!NOTE]
+> In Regular Expressions, `.` in `(twitter|x).com` is also treated as *any character*. Therefore, `(twitter|x).com/.*` also matches, for example, `twitter1com/` or `x_com/`.
+> 
+> To avoid it, you can change it to `(twitter|x)\.com/.*`. `\` is used to escape a special character.
+>
+> However, there are no such URLs in the general internet environment. Therefore, you can leave `.` as a special character if you prefer. Your rule is for your own use, so implement it as you see fit.
+
+### Step 2: Set up "Redirect To"
+
+Simply specify the URL as follows:
+
+```
+https://insighttimer.com/saraauster/guided-meditations/calm
+```
+
+Now, Redirect Web brings you to the meditation when you access Twitter!
+
+**[⬇️ Download the Rule](/rules/reduce-twitter-addiction.redirectweb)**
+
+## Case 2: Remove Query Parameters from URL
+
+Suppose there is a query parameter `source=twitter` in a URL of `example.com`, and you decided to remove it to anonymize yourself.
+
+In this case, the **Capturing Group Processing** option is the easiest way.:
+
+* **Redirect From**: `https://example.com/*` (Wildcard)
+* **Redirect To**: `$0`
+* **Capturing Group Processing**:
+    * **Group**: `$0`
+    * **Process**: Replace Occurrences
+        * **Target**: `&?source=[^&]*`
+        * **Replacement**: *(none)*
+        * **Text Pattern**: Regular Expression
+
+**[⬇️ Download the Rule](/rules/remove-parameters.redirectweb)**
+
+This rule works as follows:
+
+```
+https://example.com/?source=twitter
+↪ https://example.com/?
+
+https://example.com/?hello=world&source=twitter&foo=bar
+↪ https://example.com/?hello=world&foo=bar
+```
+
+If you want to remove more parameters, add more processes.
+
+## Case 3: Add Query Parameters to URL
+
+Let's say there is a website called `example.com` that shows a mobile layout by default, but you prefer their desktop layout. Fortunately, the website supports a `layout` query parameter to specify which layout the website displays. Let's create a rule that adds `layout=desktop` automatically.
+
+Perhaps you think you could define it as follows:
+
+* **Redirect From**: `https://example.com/.*` (Regular Expression)
+* **Redirect To**: `$0?layout=desktop`
+
+`$0` references the target URL. If you try to access `example.com/hello`, you're redirected to `example.com/hello?layout=desktop`. This feature is called *substitution*.
+
+> [!TIP]
+> Substitution is also available for the Wildcard mode since it's internally converted to Regular Expression.
+
+However, there are a few problems with these settings.
+
+### Problem 1: Infinite loop
+
+The current setting creates an infinite redirect loop since `https://example.com/.*` also targets `https://example.com/hello?layout=desktop`.
+
+In this case, you can specify an excluded URL pattern that allows you to access without redirection, like this with Regular Expression:
+
+```
+.*[&?]layout=[^&]*.*
+```
+
+* `.*`: Matches anything
+* `[&?]`: Matches either `&` or `?`
+* `[^&]*`: Matches anything except `&`
+
+### Problem 2: Can't handle existing parameters properly
+
+If the target URL already has other query parameters like `example.com/hello?theme=dark`, the destination will be `example.com/hello?theme=dark?layout=desktop` (There are two `?` in the URL) but you can only join the parameters with `&`. `?` as a special character is only allowed at the beginning of the parameters. So it's not treated as a valid parameter.
+
+In this case, change the settings like this:
+
+* **Redirect From**: `(https://example.com/[^?]*)(\?(.*))?`
+* **Redirect To**: `$1?layout=desktop&$3`
+
+Let's take a look step by step.
+
+* `(https://example.com/[^?]*)`: Matches the part until the previous character of `?`.
+    * `[^?]*` matches anything except `?`.
+    * This is wrapped with `()` so you can reference it with `$1` later.
+* `(\?(.*))?`: Matches a string start with `?`, which means query parameters.
+    * This also matches empty string by the `?` quantifier at the end of the pattern, which *matches zero or one time*.
+    * The outer `()` and the inner `()` can be referenced with `$2` and `$3` later.
+
+[RegExr](https://regexr.com) may help you understand the details.
+
+> [!NOTE]
+> RegExr shows an error when you don't escape `/` with `\`. Although you can escape it, it's not required since Redirect Web uses a different engine by Apple that doesn't require escaping.
+
+This is not a perfect solution, as it redirects `example.com/hello` to `example.com/hello?layout=desktop&`, which includes an unnecessary `&` at the end of the URL. It's not a big deal in general, but if you wish to remove it, you can use *Capturing Group Processing*.
+
+In conclusion, this is the final output:
+
+* **Redirect From**: `(https://example.com/[^?]*)((\?(.*))?)` (Regular Expression)
+* **Redirect To**: `$1?layout=desktop$3`
+* **Excluded URL Pattern**: `.*[&?]layout=[^&]*.*` (Regular Expression)
+* **Capturing Group Processing**:
+    * **Group**: `$3`
+    * **Process**: Replace Occurrences
+        * **Target**: `\?(.*)`
+        * **Replacement**: `&$1`
+
+**[⬇️ Download the Rule](/rules/add-parameters.redirectweb)**
+
+This is merely an example. You can also create multiple rules to handle each problem. It can be much simpler.