From 30af2c5685c3e33043f058490513f0fe9baafa2f Mon Sep 17 00:00:00 2001 From: liuyuweitarek Date: Mon, 28 Oct 2024 23:21:25 +0800 Subject: [PATCH] docs: update docs & typo --- README.md | 60 +++--- algolia/dev-algolia-config.json | 4 +- ...nt-Tips-Reproducibility-and-Randomness.mdx | 2 +- ...ate-a-Neuron-With-PyTorch-From-Scratch.mdx | 2 +- docs/Dev-Guide/add-new-category.md | 195 ++++++++++++++++++ docs/Dev-Guide/add-new-note.md | 117 +++++++++++ docs/Dev-Guide/index.mdx | 72 ++++--- .../renew-algolia-docsearch-index.mdx | 5 +- src/components/homepage/SocialLinks.tsx | 2 +- src/pages/index.tsx | 16 +- 10 files changed, 405 insertions(+), 70 deletions(-) create mode 100644 docs/Dev-Guide/add-new-category.md create mode 100644 docs/Dev-Guide/add-new-note.md diff --git a/README.md b/README.md index dab120e..ab71731 100644 --- a/README.md +++ b/README.md @@ -5,46 +5,58 @@ This repository contains source code of the Tarek's personal website, which is b > [!IMPORTANT] > This website originally comes from [Paweł Kosiec's awesome personal website](https://github.com/pkosiec/website). You can read more details in Paweł Kosiec's README. Appreciate his kind sharing and contribution! -## Installation +### Prerequisites -Choose one of the following: +1. Clone the repository -- Install on your computer using [npm](https://docs.npmjs.com/cli/install): +2. Install Docker and Docker Compose - ```bash - $ npm install - ``` + Please ensure that your device has successfully installed [Docker Desktop](https://www.docker.com/products/docker-desktop) or runnable [Docker Engine](https://docs.docker.com/engine/install/), and that your environment supports the `docker compose` command. -- Install with Docker, and develop in container: + ```bash + $ docker --version + Docker version 26.1.1, build 4cf5afa + + $ docker compose version + Docker Compose version v2.27.0-desktop.2 + ``` - You can find more details in the [Dev-Guide](./docs/Dev-Guide/index.mdx). +### Development - - On local machine +1. Launch the dev container ```bash - $ docker compose --profile dev up --build -d + $ docker compose --profile dev up -d ``` - - Attach on container, in container terminal +2. Access container shell ```bash - $ npm install - ``` + $ docker exec -it dev-web /bin/bash -### Local Development + # Output + root@ae3a7ef54878:/opt/website + ``` -Run following command in the terminal, based on the environment you choose, local machine or container: +3. Run the website in the container shell: -``` -$ npm start -``` + ```bash + $ npm start + ``` + You can see the website in the browser with the address. `http://localhost:3006`. -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. +4. View production build locally with: -### Build + **Build the website:** + + ``` + $ npm run build + ``` + + **Check website just built in `./build`** -``` -$ npm run build -``` + ```bash + $ npm run serve -- --host 0.0.0.0 --port 3006 --no-open + ``` -This command generates static content into the `build` directory and can be served using any static contents hosting service. +5. Renew Algolia DocSearch Index. See more in [dev-guide documents](./docs/Dev-Guide/renew-algolia-docsearch-index.mdx). diff --git a/algolia/dev-algolia-config.json b/algolia/dev-algolia-config.json index bf64a03..5c9d784 100644 --- a/algolia/dev-algolia-config.json +++ b/algolia/dev-algolia-config.json @@ -1,7 +1,7 @@ { "index_name": "dev_personal_website", - "start_urls": ["https://1f2e-42-73-214-202.ngrok-free.app"], - "sitemap_urls": ["https://1f2e-42-73-214-202.ngrok-free.app/sitemap.xml"], + "start_urls": ["https://d63d-36-226-104-66.ngrok-free.app"], + "sitemap_urls": ["https://d63d-36-226-104-66.ngrok-free.app/sitemap.xml"], "sitemap_alternate_links": true, "stop_urls": ["/tests"], "selectors": { diff --git a/docs/ComputerScience/Experiment-Tips-Reproducibility-and-Randomness.mdx b/docs/ComputerScience/Experiment-Tips-Reproducibility-and-Randomness.mdx index 1ba7335..37799f3 100644 --- a/docs/ComputerScience/Experiment-Tips-Reproducibility-and-Randomness.mdx +++ b/docs/ComputerScience/Experiment-Tips-Reproducibility-and-Randomness.mdx @@ -1,6 +1,6 @@ --- id: experiment-tips-reproducibility-and-randomness -title: "Experiment Tips: Reproducibility and Randomness" +title: "Experiment Tips - Reproducibility and Randomness" hide_title: true sidebar_position: 4 tags: ["pytorch", "computer-science"] diff --git a/docs/ComputerScience/Simulate-a-Neuron-With-PyTorch-From-Scratch.mdx b/docs/ComputerScience/Simulate-a-Neuron-With-PyTorch-From-Scratch.mdx index 1c15f13..7dd3212 100644 --- a/docs/ComputerScience/Simulate-a-Neuron-With-PyTorch-From-Scratch.mdx +++ b/docs/ComputerScience/Simulate-a-Neuron-With-PyTorch-From-Scratch.mdx @@ -3,7 +3,7 @@ id: simulate-a-neuron-with-pytorch title: Simulate a neuron with PyTorch hide_title: true sidebar_position: 3 -tags: ["pytorch", "implementation", "deep-learning", "computer-science"] +tags: ["pytorch", "deep-learning", "implementation", "computer-science"] draft: false last_update: date: 12/2/2022 diff --git a/docs/Dev-Guide/add-new-category.md b/docs/Dev-Guide/add-new-category.md new file mode 100644 index 0000000..1644174 --- /dev/null +++ b/docs/Dev-Guide/add-new-category.md @@ -0,0 +1,195 @@ +--- +id: add-new-category +title: Add a new category +hide_title: true +sidebar_position: 3 +tags: ["dev-guide"] +last_update: + date: 10/24/2024 + author: Tarek Liu +unlisted: true +--- + +:::warning +Watch out naming format! + +If new category named \"New Category\", then: + +- \: \"NewCategory\" +- \: \"new-category\" +- \: \"nc\" +- \: \"New Category\" +::: + +1. Create a new folder under `docs` folder, like `docs/NewCategory`. + +2. Add a category tag in `docs/tags.yml` file. + + - Make sure the tag name is not duplicated. + + - Tag name should be lowercase and separated by `-`. + + e.g. ComputerScience => computer-science + +3. Make new category be searchable in "Category Search Page". + + - Edit `src\data\notes.tsx` and register your note into object. + + 1. Add tag + + ``` + export type TagType = + (Add new category tags here) + | + ``` + + 2. Edit tag info + + ``` + export const Tags: { [type in TagType]: Tag } = { + : { + label: translate({ message: "" }), + description: translate({ + message: "", + id: "tagsearch.tag..description", + }), + color: "", -> hex code + }, + }; + ``` + +4. Add new category `index.mdx` in `docs/` folder. + + **`index.mdx`** + + ``` + --- + id: + title: + tags: ["manual", ] + hide_title: true + hide_table_of_contents: true + displayed_sidebar: Sidebar + sidebar_position: 2 -> Check current sidebar position + last_update: + date: 6/24/2024 -> MM/DD/YYYY, Check current date + author: Tarek Liu -> Your name + --- + + import TagSearchNotes from "@site/src/components/tagsearch/index"; + + + ``` + +5. Add new category's sidebar in `sidebars.js`. + + New category's sidebar name is `Sidebar`, e.g. `ncSidebar`. Items obj name would be like `ncItems`. + + - Add new category into home sidebar + + **`sidebars.js`** + + ``` + const homeItems = [ + { + type: 'category', + label: '', + className: '', + link: { + type: 'generated-index', + slug: '?tags=&operator=AND', + }, + collapsed: true, + items: [ + { + type: "autogenerated", + dirName: "", + } + ], + }, + ] + + ``` + + - Add new category into note category sidebar + **`sidebars.js`** + + ``` + const ncItems = [ + { + type: 'link', + href: '/docs/note', + label: 'Back to Home', + }, + { + type: 'link', + href: '/docs/?tags=&operator=AND', + label: 'Search', + }, + { + type: "autogenerated", + dirName: "" + } + ] + ``` + + ``` + const sidebars = { + homeSidebar: homeItems, + ncSidebar: ncItems --> Edit here! + }; + ``` + +6. (Optional) Customize `autogenerated` sidebar items + + At **`docusaurus.config.ts`** + + ``` + presets: [ + [ + { + docs: { + sidebarItemsGenerator: async function sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) { + const sidebarItems = await defaultSidebarItemsGenerator(args); + return skipIndex(sidebarItems); + }, + } + } + ] + ] + ``` + + Function `skipIndex` controls whether to skip some pages. + + ``` + const skipRenderNoteIDs = [ + "Psychology/psychology", + "ComputerScience/computer-science", + ] + + const retainLabels = [ + "Search", + "Back to Home" + ]; + + function skipIndex(items) { + if (typeof items !== "undefined"){ + return items.filter(({ type, id, label }) => { + return (type === 'doc' && !skipRenderNoteIDs.includes(id)) + || retainLabels.includes(label); + }); + } + return []; + } + ``` + + + + + + + + diff --git a/docs/Dev-Guide/add-new-note.md b/docs/Dev-Guide/add-new-note.md new file mode 100644 index 0000000..76c1067 --- /dev/null +++ b/docs/Dev-Guide/add-new-note.md @@ -0,0 +1,117 @@ +--- +id: add-new-note +title: Add a new note +hide_title: true +sidebar_position: 2 +tags: ["dev-guide"] +last_update: + date: 10/24/2024 + author: Tarek Liu +unlisted: true +--- + +## Add Content Note + +1. Create a new file under folder `docs/`. + + **Template** + + ``` + + --- + id: simulate-a-neuron-with-pytorch + title: Simulate a neuron with PyTorch + hide_title: true + sidebar_position: 3 + tags: ["pytorch", "implementation", "deep-learning", "computer-science"] + draft: false + last_update: + date: 12/2/2022 + author: Tarek Liu + --- + + (Import plugin here) + import Image from "@theme/IdealImage"; + import Tabs from "@theme/Tabs"; + import TabItem from "@theme/TabItem"; + + (Import image source here) + import SimpleNeuron from "../assets/computer-science/Simple-Neuron.png"; + + ``` + +2. Pick up proper tags for this note. + + Checkout `docs/tags.yml` for existing tags. + +:::note +Tags picked up here are just for tags pages and showing up in the bottom of the article. + +Tags for searching incategory page, please see more details in next step. +::: + +3. Add note to Category Search Page. + + - Edit `src\data\notes.tsx` and register your note into object. + + ``` + const Notes: Note[] = [ + { + title: "Simulate a neuron with PyTorch", + description: "Implement neural network and simulate the all-or-none laws.", + preview: require("./images/Simulate-a-neuron-with-PyTorch.png"), + website: "./ComputerScience/simulate-a-neuron-with-pytorch", + source: + "https://colab.research.google.com/drive/1x36lSmRdi8dOPkjzhhjuF8AZbnQWOnzl?usp=sharing", + tags: ["pinned", "implementation", "computer-science"], + }, + { + (Add your own note info here) + } + ]; + ``` + - Make sure `tags` contain proper category searchable tags, which also be defined in `src\data\notes.tsx`: + + ``` + export type TagType = + // Note types + | "pinned" + | "implementation" + | "insight" + | "paper-reading" + | "proof-of-concept" + | "analysis" + + // Fields + | "computer-science" + | "statistic" + | "psychology" + | "behavioral-experiment" + | "algorithm"; + ``` + + - **Pin the article with `pinned` tag.** + + +## Add Dev-Guide Note + +**Template** + +``` + +--- +id: add-new-note +title: Add a new note +hide_title: true +sidebar_position: 3 +tags: ["dev-guide"] +last_update: + date: 10/24/2024 + author: Tarek Liu +unlisted: true +--- + +``` + + + diff --git a/docs/Dev-Guide/index.mdx b/docs/Dev-Guide/index.mdx index d07bd09..2b59165 100644 --- a/docs/Dev-Guide/index.mdx +++ b/docs/Dev-Guide/index.mdx @@ -1,52 +1,62 @@ --- id: dev-guide -title: Guides For Developing in Local +hide_title: true +title: Getting Started tags: ["manual"] unlisted: true -sidebar_position: 100 +sidebar_position: 1 --- -# Prerequisites +### Prerequisites -My dev stack is composed of: +1. Clone the repository -1. [Docker Desktop](https://www.docker.com/products/docker-desktop/). +2. Install Docker and Docker Compose - If your operating system is Windows, you might need to launch WSL2 first. + Please ensure that your device has successfully installed [Docker Desktop](https://www.docker.com/products/docker-desktop) or runnable [Docker Engine](https://docs.docker.com/engine/install/), and that your environment supports the `docker compose` command. -2. [VScode IDE](https://code.visualstudio.com/) + ```bash + $ docker --version + Docker version 26.1.1, build 4cf5afa -3. VScode extension **Remote - Containers**. + $ docker compose version + Docker Compose version v2.27.0-desktop.2 + ``` +### Development - 1. Go to the Extensions view by clicking on the square icon on the left sidebar or by pressing `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (Mac). - 2. Search for **"Remote - Containers"** in the search bar. - 3. Click on the "Install" button next to the "Remote - Containers" extension. - 4. Once the extension is installed, you can follow the instructions provided in the extension's documentation to set up and use it with your project. +1. Launch the dev container - Please note that the **"VSCode Remote - Containers"** extension allows you to develop inside a containerized environment, which can be useful for Flutter projects that require specific dependencies or configurations. + ```bash + $ docker compose --profile dev up -d + ``` -# Getting Started +2. Access container shell -1. In local terminal: + ```bash + $ docker exec -it dev-web /bin/bash - ```bash - $ docker compose --profile dev up --build -d - ``` + # Output + root@ae3a7ef54878:/opt/website + ``` -2. Open VScode command palette, search "Remote-Containers: Attach to running container" in the search bar and click on the running container name that your just launched. +3. Run the website in the container shell: -# Development + ```bash + $ npm start + ``` + You can see the website in the browser with the address. `http://localhost:3006`. -1. In container terminal: +4. View production build locally with: - ```bash - $ npm start - ``` + **Build the website:** + + ``` + $ npm run build + ``` + + **Check website just built in `./build`** -2. Local build: - - ```bash - $ npm run build - ``` - -3. Renew Algolia DocSearch Index. See more in [renew-algolia-docsearch-index.mdx](./renew-algolia-docsearch-index.mdx) + ```bash + $ npm run serve -- --host 0.0.0.0 --port 3006 --no-open + ``` +5. Renew Algolia DocSearch Index. See more in [renew-algolia-docsearch-index.mdx](./renew-algolia-docsearch-index.mdx) diff --git a/docs/Dev-Guide/renew-algolia-docsearch-index.mdx b/docs/Dev-Guide/renew-algolia-docsearch-index.mdx index d93d8fa..a928d52 100644 --- a/docs/Dev-Guide/renew-algolia-docsearch-index.mdx +++ b/docs/Dev-Guide/renew-algolia-docsearch-index.mdx @@ -1,7 +1,8 @@ --- id: renew-algolia-docsearch-index title: Renew Algolia DocSearch Index -sidebar_position: 2 +hide_title: true +sidebar_position: 10 tags: ["dev-guide"] last_update: date: 6/24/2024 @@ -37,7 +38,7 @@ unlisted: true The terminal you have your ngrok installed, mine in my local machine: ```bash - $ ngrok http 3007 --region jp + $ ngrok http 3006 --region jp ``` 5. Modify your algolia config in `./algolia/dev-algolia-config.json` file. diff --git a/src/components/homepage/SocialLinks.tsx b/src/components/homepage/SocialLinks.tsx index 67c42b5..112a101 100644 --- a/src/components/homepage/SocialLinks.tsx +++ b/src/components/homepage/SocialLinks.tsx @@ -29,7 +29,7 @@ export const SocialLinks: FunctionComponent = ({ data }) => { return (
-

Social media

+

Connect to Me

{socialLinksComponents}
diff --git a/src/pages/index.tsx b/src/pages/index.tsx index 4c4190e..7fe28a3 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -33,15 +33,15 @@ const socialLinks: SocialLinkData[] = [ ), }, { - name: "HuggingFace", - url: "https://huggingface.co/liuyuweitarek", - svg: ( - - HuggingFace - + name: "StackOverflow", + url: "https://stackoverflow.com/users/14371814/yu-wei-liu", + svg:( + + StackOverflow + - ), - }, + ) + } ]; export default function Home(): JSX.Element {