docs: overhaul

adrianschubek · Apr 27, 2023 · 0116646 · 0116646
1 parent c8602f6
commit 0116646
Show file tree

Hide file tree

Showing 16 changed files with 536 additions and 76 deletions.
diff --git a/docs/docs/getting-started/usage.mdx b/docs/docs/getting-started/usage.mdx
@@ -11,13 +11,14 @@ Usage: utpp [options] <files> [variables]
 
 Options:
       --help           Show help                                       [boolean]
-      --version        Show version number                             [boolean]
+  -V, --version        Show version number                             [boolean]
   -o, --output         write to output file                             [string]
   -c, --check          checks the file's syntax only  [boolean] [default: false]
   -v, --verbose        show more debug logs           [boolean] [default: false]
   -p, --print          prints the output to stdout instead of files    [boolean]
   -q, --quiet          makes the preprocessor quiet   [boolean] [default: false]
       --ignore         glob pattern to ignore files       [string] [default: ""]
+      --encoding       encoding of the input file     [string] [default: "utf8"]
       --no-eval        disables eval function                          [boolean]
       --no-files       disables inclusion from files                   [boolean]
       --no-urls        disables inclusion from urls                    [boolean]
@@ -45,6 +46,125 @@ For example `utpp "*/**" foo=bar` will run the preprocessor on all files in the
 Or `utpp "foo.txt;bar.tex;baz.html"` will run the preprocessor on `foo.txt`, `bar.tex` and `baz.html`.
 :::
 
-:::info
+:::tip
 Show this help page by running `utpp`.
-:::
+:::
+
+### Running it on a single file
+
+```bash
+utpp input.txt
+```
+This will run the preprocessor on `input.txt` and write the output to `input.txt` as well.
+
+If you want to write the output to a different file, use the `-o` option:
+
+```bash
+utpp -o output.txt input.txt
+```
+This will run the preprocessor on `input.txt` and write the output to `output.txt`. The input file will not be modified.
+
+And if you want to print the output to stdout, use the `-p` option:
+
+```bash
+utpp -p input.txt
+```
+
+This will run the preprocessor on `input.txt` and print the output to stdout. This is useful if you want to pipe the output to another program.
+The input file will not be modified.
+
+### Running it on multiple files
+
+```bash
+utpp "*/**"
+```
+
+This will run the preprocessor on all files in the current directory and all subdirectories and write the output to the same files.
+
+If you want to write the output to stdout, use the `-p` option:
+
+```bash
+utpp -p "*/**"
+```
+
+:::info
+The `-o` option is not supported when running on multiple files.
+:::
+
+:::caution
+If you specify a wide glob pattern (such as "/**") you could run in on files you did not intend to run it on, which may result in errors.
+Make sure to read the [Safe Mode](/advanced/safe) option.
+:::
+
+### Using mutiple patterns
+
+You can specify multiple glob patterns by separating them with a semicolon <kbd>;</kbd> :
+
+```bash
+utpp "foo.txt;bar.tex;baz.html"
+```
+
+This will run the preprocessor on `foo.txt`, `bar.tex` and `baz.html` and write the output to the same files.
+
+### Ignoring files
+
+You can specify a glob pattern to ignore files by using the `--ignore` option:
+
+```bash
+utpp --ignore "*/**/*.txt" "*/**"
+```
+
+This will run the preprocessor on all files in the current directory and all subdirectories except for files ending with `.txt`.
+By seperating the patterns with a semicolon <kbd>;</kbd> you can specify multiple patterns to ignore.
+
+### Setting variables
+
+You can set variables by specifying them after the files argument:
+
+```bash
+utpp input.txt foo=bar
+```
+
+This will run the preprocessor on `input.txt` and set the variable `foo` to `bar`.
+You can also set multiple variables by leaving a space between them `foo=bar baz=qux`.
+
+:::tip
+When setting a value which contain spaces, you need to wrap it in quotes: `foo="bar baz"`.
+:::
+
+### Troubleshooting 
+
+Enable verbose mode by using the `-v` option:
+
+```bash
+utpp -v input.txt
+```
+
+This will print debug logs to the console. Checkout [Safe Mode](/advanced/safe) for further troubleshooting.
+
+### Checking the syntax only
+
+You can check the syntax of a file without running the preprocessor by using the `-c` option:
+
+```bash
+utpp -c input.txt
+```
+
+This will check the syntax of `input.txt` and print any errors to the console. Combine it with `-v` to print debug logs as well.
+
+### Silent mode
+
+You can make the preprocessor silent by using the `-q` option:
+
+```bash
+utpp -q input.txt
+```
+
+This wil supress any output to the console **except** errors. 
+
+:::tip
+You can also silence these errors and making utpp completly quiet by pipeing the output to `/dev/null`:
+
+```bash 
+utpp -q input.txt > /dev/null 2>&1
+```
diff --git a/docs/docs/intro.md b/docs/docs/intro.md
@@ -1,6 +1,5 @@
 ---
 sidebar_position: 1
-slug: /
 ---
 
 # 👋 Welcome

diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
@@ -76,17 +76,18 @@ const config = {
       image: 'img/utpp.png',
       navbar: {
         title: 'utpp',
-        logo: {
+        /* logo: {
           alt: 'My Site Logo',
           src: 'img/logo.svg',
-        },
+        }, */
         items: [
-          /*   {
-              type: 'docSidebar',
-              sidebarId: 'tutorialSidebar',
-              position: 'left',
-              label: 'Tutorial',
-            },
+          {
+            type: 'docSidebar',
+            sidebarId: 'tutorialSidebar',
+            position: 'left',
+            label: 'Docs',
+          },
+          /*  
             { to: '/blog', label: 'Blog', position: 'left' }, */
           {
             type: 'docsVersionDropdown',

diff --git a/docs/src/components/Checkmark.jsx b/docs/src/components/Checkmark.jsx
@@ -0,0 +1,12 @@
+import React from 'react'
+
+const Checkmark = () => {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" className="icon icon-tabler icon-tabler-discount-check-filled" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
+   <path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
+   <path d="M12.01 2.011a3.2 3.2 0 0 1 2.113 .797l.154 .145l.698 .698a1.2 1.2 0 0 0 .71 .341l.135 .008h1a3.2 3.2 0 0 1 3.195 3.018l.005 .182v1c0 .27 .092 .533 .258 .743l.09 .1l.697 .698a3.2 3.2 0 0 1 .147 4.382l-.145 .154l-.698 .698a1.2 1.2 0 0 0 -.341 .71l-.008 .135v1a3.2 3.2 0 0 1 -3.018 3.195l-.182 .005h-1a1.2 1.2 0 0 0 -.743 .258l-.1 .09l-.698 .697a3.2 3.2 0 0 1 -4.382 .147l-.154 -.145l-.698 -.698a1.2 1.2 0 0 0 -.71 -.341l-.135 -.008h-1a3.2 3.2 0 0 1 -3.195 -3.018l-.005 -.182v-1a1.2 1.2 0 0 0 -.258 -.743l-.09 -.1l-.697 -.698a3.2 3.2 0 0 1 -.147 -4.382l.145 -.154l.698 -.698a1.2 1.2 0 0 0 .341 -.71l.008 -.135v-1l.005 -.182a3.2 3.2 0 0 1 3.013 -3.013l.182 -.005h1a1.2 1.2 0 0 0 .743 -.258l.1 -.09l.698 -.697a3.2 3.2 0 0 1 2.269 -.944zm3.697 7.282a1 1 0 0 0 -1.414 0l-3.293 3.292l-1.293 -1.292l-.094 -.083a1 1 0 0 0 -1.32 1.497l2 2l.094 .083a1 1 0 0 0 1.32 -.083l4 -4l.083 -.094a1 1 0 0 0 -.083 -1.32z" stroke-width="0" fill="currentColor"></path>
+</svg>
+  )
+}
+
+export default Checkmark
diff --git a/docs/src/components/HomepageFeatures/index.tsx b/docs/src/components/HomepageFeatures/index.tsx
@@ -1,68 +1,58 @@
-import React from 'react';
-import clsx from 'clsx';
-import styles from './styles.module.css';
-
-type FeatureItem = {
-  title: string;
-  Svg: React.ComponentType<React.ComponentProps<'svg'>>;
-  description: JSX.Element;
-};
-
-const FeatureList: FeatureItem[] = [
-  {
-    title: 'Easy to Use',
-    Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,
-    description: (
-      <>
-        Docusaurus was designed from the ground up to be easily installed and
-        used to get your website up and running quickly.
-      </>
-    ),
-  },
-  {
-    title: 'Focus on What Matters',
-    Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default,
-    description: (
-      <>
-        Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
-        ahead and move your docs into the <code>docs</code> directory.
-      </>
-    ),
-  },
-  {
-    title: 'Powered by React',
-    Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
-    description: (
-      <>
-        Extend or customize your website layout by reusing React. Docusaurus can
-        be extended while reusing the same header and footer.
-      </>
-    ),
-  },
-];
-
-function Feature({title, Svg, description}: FeatureItem) {
-  return (
-    <div className={clsx('col col--4')}>
-      <div className="text--center">
-        <Svg className={styles.featureSvg} role="img" />
-      </div>
-      <div className="text--center padding-horiz--md">
-        <h3>{title}</h3>
-        <p>{description}</p>
-      </div>
-    </div>
-  );
-}
+import React from "react";
+import clsx from "clsx";
+import styles from "./styles.module.css";
+import Checkmark from "../Checkmark";
 
 export default function HomepageFeatures(): JSX.Element {
   return (
     <section className={styles.features}>
       <div className="container">
         <div className="row">
-          {FeatureList.map((props, idx) => (
-            <Feature key={idx} {...props} />
-          ))}
+          <div className={clsx("col col--3")}>
+            <div className="text--center">
+              <img style={{ maxHeight: "100px" }} src="/img/world.svg"></img>
+            </div>
+            <div className="text--center padding-horiz--md">
+              <h3>Runs anywhere<Checkmark/></h3>
+              <p>
+              Application is self-contained in a single binary and works on <b>all</b> platforms and <b>any</b> filetype.
+              </p>
+            </div>
+          </div>
+          <div className={clsx("col col--3")}>
+            <div className="text--center">
+              <img style={{ maxHeight: "100px" }} src="/img/logic.svg"></img>
+            </div>
+            <div className="text--center padding-horiz--md">
+              <h3>Powerful Logic<Checkmark/></h3>
+              <p>
+                Use if/else logic to modify parts of your file, import external data from APIs, output environemnt variables etc.
+              </p>
+            </div>
+          </div>
+          <div className={clsx("col col--3")}>
+            <div className="text--center">
+              <img style={{ maxHeight: "100px" }} src="/img/node.svg"></img>
+            </div>
+            <div className="text--center padding-horiz--md">
+              <h3>Execute JavaScript<Checkmark/></h3>
+              <p>
+                Run custom JS code anywhere with full access to all Node.js APIs like <i>process</i>.
+              </p>
+            </div>
+          </div>
+          <div className={clsx("col col--3")}>
+            <div className="text--center">
+              <img style={{ maxHeight: "100px" }} src="/img/docker.webp"></img>
+            </div>
+            <div className="text--center padding-horiz--md">
+              <h3>Designed for containers<Checkmark/></h3>
+              <p>
+                Easily run it in a docker container using the <i>Alpine</i> image.
+              </p>
+            </div>
+          </div>
+
         </div>
       </div>
     </section>

diff --git a/docs/src/components/HomepageFeatures/styles.module.css b/docs/src/components/HomepageFeatures/styles.module.css
@@ -3,6 +3,7 @@
   align-items: center;
   padding: 2rem 0;
   width: 100%;
+  background: var(--ifm-color-gray-100);
 }
 
 .featureSvg {