diff --git a/README.md b/README.md index aaba2fa1e..4bb4cd8fa 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,14 @@ -# Website +# Farm docs +Docs site of Farm. -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 +Install dependencies: +```bash +pnpm i ``` -Not using SSH: - -``` -$ GIT_USER= yarn deploy +Development locally: +```bash +npm start ``` -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. +Merge the changes to main will automatically publish to github pages. \ No newline at end of file diff --git a/docs/config/cli.md b/docs/config/cli.md new file mode 100644 index 000000000..01c6c5230 --- /dev/null +++ b/docs/config/cli.md @@ -0,0 +1,2 @@ +# CLI Options +WIP... \ No newline at end of file diff --git a/docs/config/farm-config.md b/docs/config/farm-config.md new file mode 100644 index 000000000..1b748aa26 --- /dev/null +++ b/docs/config/farm-config.md @@ -0,0 +1,156 @@ + +# Config Reference +Farm loads config from `farm.config.ts` or `farm.config.js` file under the project root, recommend to use `farm.config.ts` to get typing support easily. + +The config file look like: + +```ts +import { defineFarmConfig } from '@farmfe/core/dist/config'; + +export default defineFarmConfig({ + root: process.cwd(), // config project root + // Options related compilation + compilation: { + // ... + }, + // Options related to dev server + server: { + hmr: true, + // ... + }, + // Additional plugins + plugins: [] +}); +``` + +## Compilation Options +> The detail of each option will be completed later + +```ts +import { defineFarmConfig } from '@farmfe/core/dist/config'; + +export default defineFarmConfig({ + // Options related compilation + compilation: CompilationOptions; + // .. +}); + +interface CompilationOptions { + input?: Record; + output?: { + filename?: string; + path?: string; + publicPath?: string; + }; + resolve?: { + extensions?: string[]; + alias?: Record; + mainFields?: string[]; + conditions?: string[]; + symlinks: boolean; + }; + external?: string[]; + mode?: 'development' | 'production'; + runtime?: { + plugins?: string[]; // custom runtime plugin + }; + // Options parsed to swc + script?: { + // specify target es version + target?: + | 'es3' + | 'es5' + | 'es2015' + | 'es2016' + | 'es2017' + | 'es2018' + | 'es2019' + | 'es2020' + | 'es2021' + | 'es2022'; + // config swc parser + parser?: { + esConfig?: { + jsx?: boolean; + fnBind: boolean; + // Enable decorators. + decorators: boolean; + + // babel: `decorators.decoratorsBeforeExport` + // + // Effective only if `decorators` is true. + decoratorsBeforeExport: boolean; + exportDefaultFrom: boolean; + // Stage 3. + importAssertions: boolean; + privateInObject: boolean; + allowSuperOutsideMethod: boolean; + allowReturnOutsideFunction: boolean; + }; + tsConfig?: { + tsx: boolean; + decorators: boolean; + /// `.d.ts` + dts: boolean; + noEarlyErrors: boolean; + }; + }; + }; + // Specify which modules to be bundled tother + partialBundling?: { + moduleBuckets?: { + name: string; + test: string[]; + }[]; + }; + // Enable lazyCompilation or not + lazyCompilation?: boolean; +}; +``` + +## Server Options + +```ts +export default defineFarmConfig({ + // Options related compilation + server: ServerOptions; + // .. +}); + +interface ServerOptions { + https?: boolean; + port?: number; + hmr?: boolean; +} +``` + +## Plugins Options + +```ts +export default defineFarmConfig({ + // Options related compilation + plugins: (RustPlugin | JsPlugin)[]; + // .. +}); + +export type RustPlugin = + | string + | [ + string, + // eslint-disable-next-line @typescript-eslint/no-explicit-any + Record + ]; + +export interface JsPlugin { + resolve: JsPluginHook< + { + importers: string[]; + specifiers: string[]; + }, + PluginResolveHookParam, + PluginResolveHookResult + >; + + // load: JsPluginHook<{ filters: { ids: string[] }}>; +} +``` \ No newline at end of file diff --git a/docs/features/_category_.json b/docs/features/_category_.json new file mode 100644 index 000000000..f64dcb808 --- /dev/null +++ b/docs/features/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Features", + "position": 3, + "link": { + "type": "generated-index", + "description": "Features supported by Farm" + } +} diff --git a/docs/features/css.md b/docs/features/css.md new file mode 100644 index 000000000..fd99cb4c0 --- /dev/null +++ b/docs/features/css.md @@ -0,0 +1,2 @@ +# Css +WIP... \ No newline at end of file diff --git a/docs/features/html.md b/docs/features/html.md new file mode 100644 index 000000000..e76184832 --- /dev/null +++ b/docs/features/html.md @@ -0,0 +1,6 @@ +--- +sidebar_position: 1 +--- + +# Html +WIP... \ No newline at end of file diff --git a/docs/features/lazy-compilation.md b/docs/features/lazy-compilation.md new file mode 100644 index 000000000..165653561 --- /dev/null +++ b/docs/features/lazy-compilation.md @@ -0,0 +1,2 @@ +# Lazy Compilation +WIP... \ No newline at end of file diff --git a/docs/features/partial-bundling.md b/docs/features/partial-bundling.md new file mode 100644 index 000000000..28b557ee7 --- /dev/null +++ b/docs/features/partial-bundling.md @@ -0,0 +1,2 @@ +# Partial Bundling +WIP... \ No newline at end of file diff --git a/docs/features/script.md b/docs/features/script.md new file mode 100644 index 000000000..85564eada --- /dev/null +++ b/docs/features/script.md @@ -0,0 +1,3 @@ + +# Js/Jsx/Ts/Tsx +WIP... \ No newline at end of file diff --git a/docs/features/static.md b/docs/features/static.md new file mode 100644 index 000000000..6ec504739 --- /dev/null +++ b/docs/features/static.md @@ -0,0 +1,2 @@ +# Static Assets +WIP... \ No newline at end of file diff --git a/docs/intro.md b/docs/intro.md deleted file mode 100644 index 8a2e69d95..000000000 --- a/docs/intro.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Tutorial Intro - -Let's discover **Docusaurus in less than 5 minutes**. - -## Getting Started - -Get started by **creating a new site**. - -Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. - -### What you'll need - -- [Node.js](https://nodejs.org/en/download/) version 16.14 or above: - - When installing Node.js, you are recommended to check all checkboxes related to dependencies. - -## Generate a new site - -Generate a new Docusaurus site using the **classic template**. - -The classic template will automatically be added to your project after you run the command: - -```bash -npm init docusaurus@latest my-website classic -``` - -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. - -The command also installs all necessary dependencies you need to run Docusaurus. - -## Start your site - -Run the development server: - -```bash -cd my-website -npm run start -``` - -The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. - -The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. - -Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. diff --git a/docs/performance.md b/docs/performance.md new file mode 100644 index 000000000..993353f1a --- /dev/null +++ b/docs/performance.md @@ -0,0 +1,14 @@ +# Performance Compare + +For a basic React demo project: + +| | Webpack | Vite | Farm | Compare | +| ------------------- | ------- | ----- | ----- | --------------------------------------------- | +| **cold start** | 853ms | 276ms | 67ms | Farm is faster: **12x webpack**，**4x vite** | +| **HMR** | 43ms | 23ms | 2ms | Farm is faster: **20x webpack**，**10x vite** | +| **onload** | 83ms | 310ms | 57ms | Farm is faster: **5x vite** | +| **accessible time** | 936ms | 586ms | 124ms | Farm is faster: **8x webpack**，**5x vite** | + +> Test Repo：https://github.com/farm-fe/performance-compare +> +> Test Machine（Linux Mint 21.1 Cinnamon， 11th Gen Intel© Core™ i5-11400 @ 2.60GHz × 6， 15.5 GiB） \ No newline at end of file diff --git a/docs/plugins/js-plugin.md b/docs/plugins/js-plugin.md new file mode 100644 index 000000000..868b726ee --- /dev/null +++ b/docs/plugins/js-plugin.md @@ -0,0 +1,2 @@ +# Js Plugins +This doc is under construction... \ No newline at end of file diff --git a/docs/plugins/overview.md b/docs/plugins/overview.md new file mode 100644 index 000000000..5faa83251 --- /dev/null +++ b/docs/plugins/overview.md @@ -0,0 +1,3 @@ + +# Overview +This doc is under construction... \ No newline at end of file diff --git a/docs/plugins/rust-plugin.md b/docs/plugins/rust-plugin.md new file mode 100644 index 000000000..bcb2726f6 --- /dev/null +++ b/docs/plugins/rust-plugin.md @@ -0,0 +1,3 @@ + +# Rust Plugins +This doc is under construction... \ No newline at end of file diff --git a/docs/quick-start.mdx b/docs/quick-start.mdx new file mode 100644 index 000000000..1b3703402 --- /dev/null +++ b/docs/quick-start.mdx @@ -0,0 +1,90 @@ +--- +sidebar_position: 1 +--- + +import CodeBlock from '@theme/CodeBlock'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Quick Start +:::note +Farm needs **Node 16 and above**. And if you are using Linux, please make sure your os version is **ubuntu 22** and above(**with GLIBC >= 2.32**). +::: + +## 1. Create a Farm Project +Package `@farmfe/cli` provide abilities to create, start and build a Farm Project or Farm Plugin. Using `create` command to init a new Farm Project. + +```bash +npx @farmfe/cli@latest create +``` +:::note +The `create` command only support to init a simple React project for now, we will make it more powerful in the feature. +::: + +## 2. Start the Project +Install dependencies First, choose the package manager you like, `npm` or `yarn` or `pnpm`: + + + +cd farm-react && npm install + + + + +cd farm-react && yarn + + + + +cd farm-react && pnpm install + + + + +Then, start the project: + +```bash +npm start +``` + +The project will start at `http://localhost:9000` by default. + +## Configuring the Project + +The project is configured by `farm.config.ts` file in the root directory of the project. + +```ts title="farm.config.ts" +import { defineConfig } from '@farmfe/core/dist/config'; + +export default defineConfig({ + // Options related to the compilation + compilation: { + input: { + // can be a relative path or an absolute path + index: './index.html' + }, + output: { + path: './build', + publicPath: '/' + }, + // ... + }, + // Options related to the dev server + server: { + port: 9000, + // ... + }, + // Additional plugins + plugins: [], +}); +``` +:::note +Refer to **[Config Reference](/docs/config/farm-config)** for more details of configuring Farm. +::: + +## Next Steps + +- [Why Farm?](/docs/why-farm) +- [Features](/docs/features/html) +- [Config Reference](/docs/config/farm-config) +- [Plugins](/docs/plugins/overview) diff --git a/docs/tutorial-basics/_category_.json b/docs/tutorial-basics/_category_.json deleted file mode 100644 index 2e6db55b1..000000000 --- a/docs/tutorial-basics/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Tutorial - Basics", - "position": 2, - "link": { - "type": "generated-index", - "description": "5 minutes to learn the most important Docusaurus concepts." - } -} diff --git a/docs/tutorial-basics/congratulations.md b/docs/tutorial-basics/congratulations.md deleted file mode 100644 index 04771a00b..000000000 --- a/docs/tutorial-basics/congratulations.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_position: 6 ---- - -# Congratulations! - -You have just learned the **basics of Docusaurus** and made some changes to the **initial template**. - -Docusaurus has **much more to offer**! - -Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.md)** and **[i18n](../tutorial-extras/translate-your-site.md)**. - -Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus/discussions/4610) - -## What's next? - -- Read the [official documentation](https://docusaurus.io/) -- Modify your site configuration with [`docusaurus.config.js`](https://docusaurus.io/docs/api/docusaurus-config) -- Add navbar and footer items with [`themeConfig`](https://docusaurus.io/docs/api/themes/configuration) -- Add a custom [Design and Layout](https://docusaurus.io/docs/styling-layout) -- Add a [search bar](https://docusaurus.io/docs/search) -- Find inspirations in the [Docusaurus showcase](https://docusaurus.io/showcase) -- Get involved in the [Docusaurus Community](https://docusaurus.io/community/support) diff --git a/docs/tutorial-basics/create-a-blog-post.md b/docs/tutorial-basics/create-a-blog-post.md deleted file mode 100644 index ea472bbaf..000000000 --- a/docs/tutorial-basics/create-a-blog-post.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Create a Blog Post - -Docusaurus creates a **page for each blog post**, but also a **blog index page**, a **tag system**, an **RSS** feed... - -## Create your first Post - -Create a file at `blog/2021-02-28-greetings.md`: - -```md title="blog/2021-02-28-greetings.md" ---- -slug: greetings -title: Greetings! -authors: - - name: Joel Marcey - title: Co-creator of Docusaurus 1 - url: https://github.com/JoelMarcey - image_url: https://github.com/JoelMarcey.png - - name: Sébastien Lorber - title: Docusaurus maintainer - url: https://sebastienlorber.com - image_url: https://github.com/slorber.png -tags: [greetings] ---- - -Congratulations, you have made your first post! - -Feel free to play around and edit this post as much you like. -``` - -A new blog post is now available at [http://localhost:3000/blog/greetings](http://localhost:3000/blog/greetings). diff --git a/docs/tutorial-basics/create-a-document.md b/docs/tutorial-basics/create-a-document.md deleted file mode 100644 index ffddfa8eb..000000000 --- a/docs/tutorial-basics/create-a-document.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Create a Document - -Documents are **groups of pages** connected through: - -- a **sidebar** -- **previous/next navigation** -- **versioning** - -## Create your first Doc - -Create a Markdown file at `docs/hello.md`: - -```md title="docs/hello.md" -# Hello - -This is my **first Docusaurus document**! -``` - -A new document is now available at [http://localhost:3000/docs/hello](http://localhost:3000/docs/hello). - -## Configure the Sidebar - -Docusaurus automatically **creates a sidebar** from the `docs` folder. - -Add metadata to customize the sidebar label and position: - -```md title="docs/hello.md" {1-4} ---- -sidebar_label: 'Hi!' -sidebar_position: 3 ---- - -# Hello - -This is my **first Docusaurus document**! -``` - -It is also possible to create your sidebar explicitly in `sidebars.js`: - -```js title="sidebars.js" -module.exports = { - tutorialSidebar: [ - 'intro', - // highlight-next-line - 'hello', - { - type: 'category', - label: 'Tutorial', - items: ['tutorial-basics/create-a-document'], - }, - ], -}; -``` diff --git a/docs/tutorial-basics/create-a-page.md b/docs/tutorial-basics/create-a-page.md deleted file mode 100644 index 20e2ac300..000000000 --- a/docs/tutorial-basics/create-a-page.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Create a Page - -Add **Markdown or React** files to `src/pages` to create a **standalone page**: - -- `src/pages/index.js` → `localhost:3000/` -- `src/pages/foo.md` → `localhost:3000/foo` -- `src/pages/foo/bar.js` → `localhost:3000/foo/bar` - -## Create your first React Page - -Create a file at `src/pages/my-react-page.js`: - -```jsx title="src/pages/my-react-page.js" -import React from 'react'; -import Layout from '@theme/Layout'; - -export default function MyReactPage() { - return ( - -

My React page

-

This is a React page

- - ); -} -``` - -A new page is now available at [http://localhost:3000/my-react-page](http://localhost:3000/my-react-page). - -## Create your first Markdown Page - -Create a file at `src/pages/my-markdown-page.md`: - -```mdx title="src/pages/my-markdown-page.md" -# My Markdown page - -This is a Markdown page -``` - -A new page is now available at [http://localhost:3000/my-markdown-page](http://localhost:3000/my-markdown-page). diff --git a/docs/tutorial-basics/deploy-your-site.md b/docs/tutorial-basics/deploy-your-site.md deleted file mode 100644 index 1c50ee063..000000000 --- a/docs/tutorial-basics/deploy-your-site.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -sidebar_position: 5 ---- - -# Deploy your site - -Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**). - -It builds your site as simple **static HTML, JavaScript and CSS files**. - -## Build your site - -Build your site **for production**: - -```bash -npm run build -``` - -The static files are generated in the `build` folder. - -## Deploy your site - -Test your production build locally: - -```bash -npm run serve -``` - -The `build` folder is now served at [http://localhost:3000/](http://localhost:3000/). - -You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**). diff --git a/docs/tutorial-basics/markdown-features.mdx b/docs/tutorial-basics/markdown-features.mdx deleted file mode 100644 index 0337f34d6..000000000 --- a/docs/tutorial-basics/markdown-features.mdx +++ /dev/null @@ -1,150 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Markdown Features - -Docusaurus supports **[Markdown](https://daringfireball.net/projects/markdown/syntax)** and a few **additional features**. - -## Front Matter - -Markdown documents have metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/): - -```text title="my-doc.md" -// highlight-start ---- -id: my-doc-id -title: My document title -description: My document description -slug: /my-custom-url ---- -// highlight-end - -## Markdown heading - -Markdown text with [links](./hello.md) -``` - -## Links - -Regular Markdown links are supported, using url paths or relative file paths. - -```md -Let's see how to [Create a page](/create-a-page). -``` - -```md -Let's see how to [Create a page](./create-a-page.md). -``` - -**Result:** Let's see how to [Create a page](./create-a-page.md). - -## Images - -Regular Markdown images are supported. - -You can use absolute paths to reference images in the static directory (`static/img/docusaurus.png`): - -```md -![Docusaurus logo](/img/docusaurus.png) -``` - -![Docusaurus logo](/img/docusaurus.png) - -You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them: - -```md -![Docusaurus logo](./img/docusaurus.png) -``` - -## Code Blocks - -Markdown code blocks are supported with Syntax highlighting. - - ```jsx title="src/components/HelloDocusaurus.js" - function HelloDocusaurus() { - return ( -

Hello, Docusaurus!

- ) - } - ``` - -```jsx title="src/components/HelloDocusaurus.js" -function HelloDocusaurus() { - return

Hello, Docusaurus!

; -} -``` - -## Admonitions - -Docusaurus has a special syntax to create admonitions and callouts: - - :::tip My tip - - Use this awesome feature option - - ::: - - :::danger Take care - - This action is dangerous - - ::: - -:::tip My tip - -Use this awesome feature option - -::: - -:::danger Take care - -This action is dangerous - -::: - -## MDX and React Components - -[MDX](https://mdxjs.com/) can make your documentation more **interactive** and allows using any **React components inside Markdown**: - -```jsx -export const Highlight = ({children, color}) => ( - { - alert(`You clicked the color ${color} with label ${children}`) - }}> - {children} - -); - -This is Docusaurus green ! - -This is Facebook blue ! -``` - -export const Highlight = ({children, color}) => ( - { - alert(`You clicked the color ${color} with label ${children}`); - }}> - {children} - -); - -This is Docusaurus green ! - -This is Facebook blue ! diff --git a/docs/tutorial-extras/_category_.json b/docs/tutorial-extras/_category_.json deleted file mode 100644 index a8ffcc193..000000000 --- a/docs/tutorial-extras/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "label": "Tutorial - Extras", - "position": 3, - "link": { - "type": "generated-index" - } -} diff --git a/docs/tutorial-extras/img/docsVersionDropdown.png b/docs/tutorial-extras/img/docsVersionDropdown.png deleted file mode 100644 index 97e416461..000000000 Binary files a/docs/tutorial-extras/img/docsVersionDropdown.png and /dev/null differ diff --git a/docs/tutorial-extras/img/localeDropdown.png b/docs/tutorial-extras/img/localeDropdown.png deleted file mode 100644 index e257edc1f..000000000 Binary files a/docs/tutorial-extras/img/localeDropdown.png and /dev/null differ diff --git a/docs/tutorial-extras/manage-docs-versions.md b/docs/tutorial-extras/manage-docs-versions.md deleted file mode 100644 index e12c3f344..000000000 --- a/docs/tutorial-extras/manage-docs-versions.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Manage Docs Versions - -Docusaurus can manage multiple versions of your docs. - -## Create a docs version - -Release a version 1.0 of your project: - -```bash -npm run docusaurus docs:version 1.0 -``` - -The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created. - -Your docs now have 2 versions: - -- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs -- `current` at `http://localhost:3000/docs/next/` for the **upcoming, unreleased docs** - -## Add a Version Dropdown - -To navigate seamlessly across versions, add a version dropdown. - -Modify the `docusaurus.config.js` file: - -```js title="docusaurus.config.js" -module.exports = { - themeConfig: { - navbar: { - items: [ - // highlight-start - { - type: 'docsVersionDropdown', - }, - // highlight-end - ], - }, - }, -}; -``` - -The docs version dropdown appears in your navbar: - -![Docs Version Dropdown](./img/docsVersionDropdown.png) - -## Update an existing version - -It is possible to edit versioned docs in their respective folder: - -- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello` -- `docs/hello.md` updates `http://localhost:3000/docs/next/hello` diff --git a/docs/tutorial-extras/translate-your-site.md b/docs/tutorial-extras/translate-your-site.md deleted file mode 100644 index caeaffb05..000000000 --- a/docs/tutorial-extras/translate-your-site.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Translate your site - -Let's translate `docs/intro.md` to French. - -## Configure i18n - -Modify `docusaurus.config.js` to add support for the `fr` locale: - -```js title="docusaurus.config.js" -module.exports = { - i18n: { - defaultLocale: 'en', - locales: ['en', 'fr'], - }, -}; -``` - -## Translate a doc - -Copy the `docs/intro.md` file to the `i18n/fr` folder: - -```bash -mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/ - -cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md -``` - -Translate `i18n/fr/docusaurus-plugin-content-docs/current/intro.md` in French. - -## Start your localized site - -Start your site on the French locale: - -```bash -npm run start -- --locale fr -``` - -Your localized site is accessible at [http://localhost:3000/fr/](http://localhost:3000/fr/) and the `Getting Started` page is translated. - -:::caution - -In development, you can only use one locale at a same time. - -::: - -## Add a Locale Dropdown - -To navigate seamlessly across languages, add a locale dropdown. - -Modify the `docusaurus.config.js` file: - -```js title="docusaurus.config.js" -module.exports = { - themeConfig: { - navbar: { - items: [ - // highlight-start - { - type: 'localeDropdown', - }, - // highlight-end - ], - }, - }, -}; -``` - -The locale dropdown now appears in your navbar: - -![Locale Dropdown](./img/localeDropdown.png) - -## Build your localized site - -Build your site for a specific locale: - -```bash -npm run build -- --locale fr -``` - -Or build your site to include all the locales at once: - -```bash -npm run build -``` diff --git a/docs/why-farm.md b/docs/why-farm.md new file mode 100644 index 000000000..ea45e9c86 --- /dev/null +++ b/docs/why-farm.md @@ -0,0 +1,30 @@ +--- +sidebar_position: 2 +--- + +# Why Farm? + +As the web project scales, building performance has been the major bottleneck, for a huge project, compiling with webpack may cost 10min or more, a hmr update may cost 10s or more, heavily reduced the efficiency. + +Then some tools like vite comes out, it uses native ESM and is unbundled for source files in dev mode, pre-bundle dependencies using esbuild, which makes the dev server launch and the HMR very fast. + +But Unbundled is not perfect, there are still big problem when comes for a large project: +* **The huge numbers of module requests**: For a large project, there may be thousands of modules that should be loaded, using native module system to load thousands of modules will make the browser get stuck or even crashed. +* **Inconsistency between Dev and Production**: Native module can not be used in production for most situations, For the compatibility and request numbers. So Unbundled tools choose to bundle in production. This brings inconsistency, when there are production bugs caused by this inconsistency, it's really hard to debug and really painful. And vite is using esbuild in dev and using rollup in production, which enlarged the inconsistency. +* And Vite is so fast in dev because of esbuild, which is written in go. Go takes advantages of native platform and much faster than Js. + +So I thing we just need a fast, powerful, consistent web bundler, which can solve the problems above and fast, then I designed Farm. + +And Farm is not just a normal bundler re-written in Rust, it has a lot of powerful and progressive designs: + +## Farm Design Philosophy + +* **Performance first**: Everything will be written in Rust as long as we can, only several parts which is not the performance bottleneck will be written in JS +* **Consistence first**: Make sure that the development and production exactly the same by default, what you see in development will be the same as what you got in production. +* **Partial Bundling**: The bundling goal of Farm is not to bundle everything together, but to limit the request numbers of resources. Farm will bundle your project into 20-30 small resources according to the dependency relation and resource size, to get the best resources loading performance without losing caching granularity. +* **First class citizen support of all web assets**: Farm won't need to transform everything to Javascript any more, it treats anything as first class citizen, assets like `html`, `js/jsx/ts/tsx`, `css/scss`, `png/svg/...` are all basic modules supported by Farm, more assets can be supported by plugins. +* **Compatibility**: Farm will work with both legacy(ES5) and modern browser. +* **Rollup style plugin system**: Easy to create your own plugins and easy to migrate your plugins/projects from rollup/vite/webpack. + + +Farm's goal is to be the real next generation build tool, fast, powerful, consistent, and providing best development experience for web developers. \ No newline at end of file diff --git a/docusaurus.config.js b/docusaurus.config.js index 10656663a..c9f54aa1e 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -6,8 +6,8 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula'); /** @type {import('@docusaurus/types').Config} */ const config = { - title: 'My Site', - tagline: 'Dinosaurs are cool', + title: 'Farm', + tagline: 'Supper fast web build tool written in Rust', favicon: 'img/favicon.ico', // Set the production url of your site here @@ -43,7 +43,7 @@ const config = { // Please change this to your repo. // Remove this to remove the "edit this page" links. editUrl: - 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/', + 'https://github.com/farm-fe/farm-fe.github.io', }, blog: { showReadingTime: true, @@ -65,22 +65,34 @@ const config = { // Replace with your project's social card image: 'img/docusaurus-social-card.jpg', navbar: { - title: 'My Site', + title: 'Farm', logo: { alt: 'My Site Logo', - src: 'img/logo.svg', + src: 'img/logo.png', }, items: [ { type: 'doc', - docId: 'intro', + docId: 'quick-start', + position: 'left', + label: 'Guides', + }, + { + type: 'doc', + docId: 'config/farm-config', position: 'left', - label: 'Tutorial', + label: 'Config', }, - {to: '/blog', label: 'Blog', position: 'left'}, { - href: 'https://github.com/facebook/docusaurus', - label: 'GitHub', + type: 'doc', + docId: 'plugins/overview', + position: 'left', + label: 'Plugins', + }, + // {to: '/blog', label: 'Blog', position: 'left'}, + { + href: 'https://github.com/farm-fe/farm', + html: 'GitHub', position: 'right', }, ], @@ -92,25 +104,8 @@ const config = { title: 'Docs', items: [ { - label: 'Tutorial', - to: '/docs/intro', - }, - ], - }, - { - title: 'Community', - items: [ - { - label: 'Stack Overflow', - href: 'https://stackoverflow.com/questions/tagged/docusaurus', - }, - { - label: 'Discord', - href: 'https://discordapp.com/invite/docusaurus', - }, - { - label: 'Twitter', - href: 'https://twitter.com/docusaurus', + label: 'Guilds', + to: '/docs/quick-start', }, ], }, @@ -123,12 +118,12 @@ const config = { }, { label: 'GitHub', - href: 'https://github.com/facebook/docusaurus', + href: 'https://github.com/farm-fe/farm', }, ], }, ], - copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`, + copyright: `Copyright © ${new Date().getFullYear()} Farm, Inc. Built with Docusaurus.`, }, prism: { theme: lightCodeTheme, diff --git a/sidebars.js b/sidebars.js index 9ab54c245..1226f070c 100644 --- a/sidebars.js +++ b/sidebars.js @@ -14,20 +14,28 @@ /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { // By default, Docusaurus generates a sidebar from the docs folder structure - tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], + // tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], // But you can create a sidebar manually - /* tutorialSidebar: [ - 'intro', - 'hello', + 'quick-start', + 'why-farm', { type: 'category', - label: 'Tutorial', - items: ['tutorial-basics/create-a-document'], + label: 'Features', + items: ['features/html', 'features/css', 'features/script', 'features/static', 'features/lazy-compilation', 'features/partial-bundling'], }, + 'performance', ], - */ + configSidebar: [ + 'config/farm-config', + 'config/cli' + ], + pluginSidebar: [ + 'plugins/overview', + 'plugins/rust-plugin', + 'plugins/js-plugin', + ] }; module.exports = sidebars; diff --git a/src/components/HomepageFeatures/index.js b/src/components/HomepageFeatures/index.js index 78f410ba6..36a897f43 100644 --- a/src/components/HomepageFeatures/index.js +++ b/src/components/HomepageFeatures/index.js @@ -4,18 +4,17 @@ import styles from './styles.module.css'; const FeatureList = [ { - title: 'Easy to Use', - Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default, + title: 'Supper Fast', + Img: require('@site/static/img/rocket.svg').default, description: ( <> - Docusaurus was designed from the ground up to be easily installed and - used to get your website up and running quickly. + Farm is written in Rust, with multi-threading, persist caching and asynchronous compilation, which makes it super fast. ), }, { - title: 'Focus on What Matters', - Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default, + title: 'Rich Features', + Img: require('@site/static/img/toolbox.svg').default, description: ( <> Docusaurus lets you focus on your docs, and we'll do the chores. Go @@ -24,8 +23,8 @@ const FeatureList = [ ), }, { - title: 'Powered by React', - Svg: require('@site/static/img/undraw_docusaurus_react.svg').default, + title: 'Fully Pluggable', + Img: require('@site/static/img/plug.svg').default, description: ( <> Extend or customize your website layout by reusing React. Docusaurus can @@ -35,11 +34,11 @@ const FeatureList = [ }, ]; -function Feature({Svg, title, description}) { +function Feature({Img, title, description}) { return (
- +

{title}

diff --git a/src/components/HomepageFeatures/styles.module.css b/src/components/HomepageFeatures/styles.module.css index b248eb2e5..327b1fe70 100644 --- a/src/components/HomepageFeatures/styles.module.css +++ b/src/components/HomepageFeatures/styles.module.css @@ -6,6 +6,6 @@ } .featureSvg { - height: 200px; - width: 200px; + height: 100px; + width: 100px; } diff --git a/src/css/custom.css b/src/css/custom.css index 2bc6a4cfd..b6b70f68d 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -6,13 +6,13 @@ /* You can override the default Infima variables here. */ :root { - --ifm-color-primary: #2e8555; - --ifm-color-primary-dark: #29784c; - --ifm-color-primary-darker: #277148; - --ifm-color-primary-darkest: #205d3b; - --ifm-color-primary-light: #33925d; - --ifm-color-primary-lighter: #359962; - --ifm-color-primary-lightest: #3cad6e; + --ifm-color-primary: #8f1a7f; + --ifm-color-primary-dark: #6f1a5f; + --ifm-color-primary-darker: #5f1a4f; + --ifm-color-primary-darkest: #4f1a3f; + --ifm-color-primary-light: #9f1a8f; + --ifm-color-primary-lighter: #af1a9f; + --ifm-color-primary-lightest: #bf1aaf; --ifm-code-font-size: 95%; --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); } @@ -28,3 +28,12 @@ --ifm-color-primary-lightest: #4fddbf; --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); } + +.navbar__title { + color: #6f1a5f; + font-size: 1.5em; +} + +.navbar__title:hover { + color: #bf1aaf; +} \ No newline at end of file diff --git a/src/pages/index.js b/src/pages/index.js index affcd9099..db308f8a3 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -17,8 +17,14 @@ function HomepageHeader() {
- Docusaurus Tutorial - 5min ⏱️ + to="/docs/quick-start"> + Quick Start ⏱️ + + + Why Farm?
diff --git a/static/img/favicon.ico b/static/img/favicon.ico index 5a2150efd..80465dedc 100644 Binary files a/static/img/favicon.ico and b/static/img/favicon.ico differ diff --git a/static/img/github-mark.svg b/static/img/github-mark.svg new file mode 100644 index 000000000..37fa923df --- /dev/null +++ b/static/img/github-mark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/static/img/logo.png b/static/img/logo.png new file mode 100644 index 000000000..0caeb4381 Binary files /dev/null and b/static/img/logo.png differ diff --git a/static/img/logo.svg b/static/img/logo.svg deleted file mode 100644 index 9db6d0d06..000000000 --- a/static/img/logo.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/static/img/plug.svg b/static/img/plug.svg new file mode 100644 index 000000000..929a811ca --- /dev/null +++ b/static/img/plug.svg @@ -0,0 +1,59 @@ + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + Openclipart + + + icon bus bar + 2007-04-18T02:48:48 + simple red circular icon with white simplified power cord + http://openclipart.org/detail/3987/icon-bus-bar-by-jportugall + + + JPortugall + + + + + clip art + clipart + event + icon + image + media + microphone + organization + public domain + svg + + + + + + + + + + + diff --git a/static/img/rocket.svg b/static/img/rocket.svg new file mode 100644 index 000000000..b46f58aed --- /dev/null +++ b/static/img/rocket.svg @@ -0,0 +1,396 @@ + + + + + image/svg+xml + + image/svg+xml + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/static/img/toolbox.svg b/static/img/toolbox.svg new file mode 100644 index 000000000..83b3e7a5a --- /dev/null +++ b/static/img/toolbox.svg @@ -0,0 +1,4272 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + Openclipart + + + + + + + + + + + diff --git a/static/img/undraw_docusaurus_mountain.svg b/static/img/undraw_docusaurus_mountain.svg deleted file mode 100644 index af961c49a..000000000 --- a/static/img/undraw_docusaurus_mountain.svg +++ /dev/null @@ -1,171 +0,0 @@ - - Easy to Use - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/static/img/undraw_docusaurus_react.svg b/static/img/undraw_docusaurus_react.svg deleted file mode 100644 index 94b5cf08f..000000000 --- a/static/img/undraw_docusaurus_react.svg +++ /dev/null @@ -1,170 +0,0 @@ - - Powered by React - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/static/img/undraw_docusaurus_tree.svg b/static/img/undraw_docusaurus_tree.svg deleted file mode 100644 index d9161d339..000000000 --- a/static/img/undraw_docusaurus_tree.svg +++ /dev/null @@ -1,40 +0,0 @@ - - Focus on What Matters - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -