From 3475567ea6f085f12889232c4300580edc13a961 Mon Sep 17 00:00:00 2001 From: Lisa Gunn Date: Thu, 2 Nov 2023 16:12:46 -0700 Subject: [PATCH 1/7] WIP --- packages/apps/docs/README.md | 172 +++++++++++++++++++++++++++-------- 1 file changed, 133 insertions(+), 39 deletions(-) diff --git a/packages/apps/docs/README.md b/packages/apps/docs/README.md index 645c817a0d..ecf5367403 100644 --- a/packages/apps/docs/README.md +++ b/packages/apps/docs/README.md @@ -1,47 +1,141 @@ -# Contribute to the docs - -In this document you can find all the info you need to contribute to the docs. - -## Structure of the app - -When you have cloned the repo and found this package, you are almost good to go. -run the following - -``` -pnpm install -``` - -to run the app on `http://localhost:3000` - -``` -pnpm dev -``` - -Most of the files are just there for the application it self. -For writing the actual docs, the only real important folder is `/src/pages`. -This is basically the root of the application. The folders create the menu -structure you can find in the application it self. Most of the folders in the -`/src/pages` folder are also in the mainheader menu. - -Some things to consider: +--- +title: Contribute to Kadena documentation +description: Follow this guide to learn how you can contribute changes to Kadena documentation. +keywords: + - developer documentation + - Kadena blockchain +--- -- `/api` this is not a place to add documentation. This folder is used by the - application itself, to do REST API calls. -- `/search` is normally also not used to put documentation. Here you can find - the files for the actual search of the application. +We encourage everyone with an interest in improving Kadena documentation to contribute content, submit issues, and suggest changes. +This guide describes how you can make changes to the documentation website directly by editing source files or indirectly by requesting updates. +You can follow these instructions whether you are an internal or external contributor. + +## Prerequisites + +Before you begin, verify that you meet the following basic requirements: + +- You have a code editor, a GitHub account, and experience using command-line programs, including `git` commands and command line options. +- You are familiar with using the Markdown markup language to add formatting elements to plain text documents. + For information about using Markdown, see the [Markdown Guide](https://www.markdownguide.org/). -All the other files (especially with the extension `md` or `mdx`) are the actual -documentation files and you can do basically do anything with them +- You have the `pnpm` package manager installed. + + Depending on your development environment, you can install `pnpm` using a standalone script or using a package manager. + For example, you can run the command `brew install pnpm` or `npm install --global pnpm` to install `pnpm` on your local computer. + For more information about installing `pnpm` on different operating systems, see [Installation](https://pnpm.io/installation). + + Run `pnpm --version` to verify that you have `pnpm` installed and the version you are running. -## Adding a page +## Set up a local development environment -A new page can be placed anywhere in the `src/pages` tree. -Be aware that the tree can not be deeper than **3** folders. +To set up a local development environment for contributing to Kadena documentation: + +1. Open a terminal shell on your computer. -All the documentation is written in markdown. -Markdown is a lightweight markup language that you can use to add formatting -elements to plaintext text documents. You can learn more about -[Markdown here](https://www.markdownguide.org/). +1. Clone the `kadena-js` repository by running the following command: + + ```code + git clone https://github.com/kadena-community/kadena.js.git + ``` + + This command clones the entire public repository for the TypeScript and JavaScript tools that enable you to interact with the Kadena ecosystem, including the documentation package. + +2. Change to the root of the `docs` directory by running the following command: + + ```code + cd kadena.js/packages/apps/docs + ``` + +3. Install the documentation package dependencies by running the following commands: + + ```code + pnpm install + ``` + + This command installs all of the package dependencies used to build the documentation website and provide basic features, like navigation and search functionality. + To contribute to documentation, you typically only need to work in the `/src/pages` folder and its subfolders. + Most of the sub-folders and files in the `/src/pages` folder define the structure and operation of the application. + For example: + + - `/api` contains scripts to interact with the website using REST API calls. + - `/authors` contains scripts to capture blog post authors. + - `/blogchain` maintains the archive of blog post articles. + - `/build` contains sub-folders and Markdown files with information for builders. + - `/chainweb` contains a script to include Chainweb documentation that is generated automatically in the website. + - `/contribute` contains documentation related to community activities. + - `/help` contains a placeholder for displaying help topics. + - `/kadena` contains sub-folders and Markdown files with information about Kadena, including core concepts and terminology. + - `/marmalade` contains sub-folders and Markdown files with information about Marmalade, including architecture and metadata. + - `/pact` contains sub-folders and Markdown files with information about the PACT language, including tutorials, examples, and reference. + - `/search` contains the script used to search for information in the application. + - `/tags` contains scripts to capture blog post tags. + + Within these folders, the Markdown files—files with the `md` or `mdx` extension—contain the documentation content. + After you explore these folders, create a local working branch of the repository for your contribution. + +4. Create a local branch with a prefix that identifies you as the author and a branch name that describes the content you intend to add or change. + For example, if your git handle is `lola-pistola` and you are fixing a typo in the kadena folder, you might create a branch like this: + + ```code + git switch -c lola-pistola/typo-kadena-kda-concepts + ``` + +## Start a local development server + +As you make changes to the content in your local branch, it's helpful to see how the changes will be +rendered when the documentation is published. + +You can use `pnpm dev` to run a local development server that detects changes to the documentation and displays them automatically in the browser. + +To start the development server in your local environment: + +1. Change to the React component library by running the following command: + + ```code + cd kadena.js/packages/libs/react-ui + ``` + +1. Build the component library locally by running the following command: + + ```code + pnpm build + ``` + +1. Change your current working directory to `kadena-js/packages/apps/docs`. + + ```code + cd ../../apps/docs + ``` + +2. Start the development server by running the following command: + + ```code + pnpm dev + ``` + +3. Open a web browser and navigate to the documentation using the URL `localhost:3000/docs`. + +## Adding a new page + +You can add a new page anywhere in the `src/pages` folder to add a topic to the structure of the information architecture. +You can build a navigational structure up to three levels deep. + +The top navigation header is constructed from folders in the `src/pages` folder. +Currently, the top navigation has the following top-level sections: + +- Kadena +- Build +- Pact +- Chainweb +- Marmalade +- Contribute +- BlogChain + +Quick start > Brief intro to Hello, World! to navigating the documentation: +Engage > Learn > Concepts +Onboard > Discover > Tutorials (guided journey) +Coach > Build > Guides > How-to (task-based scenarios) +Propel > Advance > Deeper dives and reference Create a `.md` file. The name of the file is also the name of the URL. Make it a good one. Best is to make it the title of the document. For `spaces`, please use From e1d72176cd03bb683df3d690c9580e94c4bc078c Mon Sep 17 00:00:00 2001 From: Lisa Gunn Date: Mon, 6 Nov 2023 13:59:05 -0800 Subject: [PATCH 2/7] Draft basics for working in the repo as-is --- packages/apps/docs/README.md | 342 ++++++++++++++++------------------- 1 file changed, 152 insertions(+), 190 deletions(-) diff --git a/packages/apps/docs/README.md b/packages/apps/docs/README.md index ecf5367403..48af79ebca 100644 --- a/packages/apps/docs/README.md +++ b/packages/apps/docs/README.md @@ -10,12 +10,12 @@ We encourage everyone with an interest in improving Kadena documentation to cont This guide describes how you can make changes to the documentation website directly by editing source files or indirectly by requesting updates. You can follow these instructions whether you are an internal or external contributor. -## Prerequisites +## Before you begin -Before you begin, verify that you meet the following basic requirements: +To follow the steps in this guide, verify the following basic requirements: - You have a code editor, a GitHub account, and experience using command-line programs, including `git` commands and command line options. -- You are familiar with using the Markdown markup language to add formatting elements to plain text documents. +- You are familiar with using Markdown to add formatting elements to plain text documents. For information about using Markdown, see the [Markdown Guide](https://www.markdownguide.org/). - You have the `pnpm` package manager installed. @@ -26,6 +26,8 @@ Before you begin, verify that you meet the following basic requirements: Run `pnpm --version` to verify that you have `pnpm` installed and the version you are running. +- You have run `pnpm setup` to add pnpm to your PATH environment variable and updated your terminal to use the new PATH. + ## Set up a local development environment To set up a local development environment for contributing to Kadena documentation: @@ -38,23 +40,40 @@ To set up a local development environment for contributing to Kadena documentati git clone https://github.com/kadena-community/kadena.js.git ``` - This command clones the entire public repository for the TypeScript and JavaScript tools that enable you to interact with the Kadena ecosystem, including the documentation package. + This command clones the entire public repository for the TypeScript and JavaScript tools that enable you to interact with the Kadena ecosystem, including the documentation engine and user interface components. -2. Change to the root of the `docs` directory by running the following command: +2. Change to the root of the `kadena-js` repository by running the following command: ```code - cd kadena.js/packages/apps/docs + cd kadena.js ``` -3. Install the documentation package dependencies by running the following commands: +3. Install the workspace dependencies by running the following command: ```code pnpm install ``` - This command installs all of the package dependencies used to build the documentation website and provide basic features, like navigation and search functionality. - To contribute to documentation, you typically only need to work in the `/src/pages` folder and its subfolders. - Most of the sub-folders and files in the `/src/pages` folder define the structure and operation of the application. + This command installs all of the workspace dependencies used to build the documentation as a web application, including shared user interface components. + + +4. Install the `turbo` virtualization software by running the following command: + + ``` + pnpm install --global turbo + ``` + + After you run this command, your local workspace has everything you need to build the documentation locally. + +5. Change to the root of the `docs` application directory by running the following command: + + ```code + cd kadena.js/packages/apps/docs + ``` + + If you explore the contents of the `docs` directory, you'll see the files and subfolders used to build the documentation as a web application. + To contribute to documentation, you typically only need to work in the `/src/pages` folder and its subfolders and individual pages. + The `/src/pages` folder includes files and subfolders that define the structure of the content and the operation of the application. For example: - `/api` contains scripts to interact with the website using REST API calls. @@ -73,7 +92,7 @@ To set up a local development environment for contributing to Kadena documentati Within these folders, the Markdown files—files with the `md` or `mdx` extension—contain the documentation content. After you explore these folders, create a local working branch of the repository for your contribution. -4. Create a local branch with a prefix that identifies you as the author and a branch name that describes the content you intend to add or change. +6. Create a local branch with a prefix that identifies you as the author and a branch name that describes the content you intend to add or change. For example, if your git handle is `lola-pistola` and you are fixing a typo in the kadena folder, you might create a branch like this: ```code @@ -89,39 +108,41 @@ You can use `pnpm dev` to run a local development server that detects changes to To start the development server in your local environment: -1. Change to the React component library by running the following command: +1. Open a terminal shell and switch to your working branch, if necessary. + For example: ```code - cd kadena.js/packages/libs/react-ui + git switch lola-pistola/typo-kadena-kda-concepts ``` -1. Build the component library locally by running the following command: +1. Build the docs application by running the following command: - ```code - pnpm build + ``` + turbo run build --filter @kadena/docs^... ``` -1. Change your current working directory to `kadena-js/packages/apps/docs`. +2. Change to the `docs` application directory by running the following command: ```code - cd ../../apps/docs + cd kadena.js/packages/apps/docs ``` - -2. Start the development server by running the following command: + +3. Start the development server by running the following command: ```code pnpm dev ``` -3. Open a web browser and navigate to the documentation using the URL `localhost:3000/docs`. + This step imports files from multiple locations and can take some time to complete. -## Adding a new page +4. Open a web browser and navigate to the documentation using the URL `localhost:3000`. + + This step compiles the application and displays the top-level landing page. -You can add a new page anywhere in the `src/pages` folder to add a topic to the structure of the information architecture. -You can build a navigational structure up to three levels deep. +## Structure content using folders and pages -The top navigation header is constructed from folders in the `src/pages` folder. -Currently, the top navigation has the following top-level sections: +The top-level landing page—including the text and curated links—is defined in the file `packages/apps/docs/src/pages/index.tsx`. +Currently, the top navigation header has the following top-level sections: - Kadena - Build @@ -131,174 +152,143 @@ Currently, the top navigation has the following top-level sections: - Contribute - BlogChain -Quick start > Brief intro to Hello, World! to navigating the documentation: -Engage > Learn > Concepts -Onboard > Discover > Tutorials (guided journey) -Coach > Build > Guides > How-to (task-based scenarios) -Propel > Advance > Deeper dives and reference +These top navigation links correspond to folders in the `src/pages` folder. +The landing page for each section also contains hard-coded text in the index.tsx file for that section. +For example, the Build section landing page is `packages/apps/docs/src/pages/build/index.tsx`. +Subsections within each top-level folder are grouped into folders and each folder has an `index.md` file for its first page of content. -Create a `.md` file. The name of the file is also the name of the URL. Make it a -good one. Best is to make it the title of the document. For `spaces`, please use -`-`. Correct file name: +You can add pages to the existing structure to add a topic to the current information architecture. +The navigational structure can be up to three levels deep. +For example: -- `new-docs-application.md` +- Top level (1) folder: Build +- Second level (2) folder: Cookbooks +- Third level (3) page: index.md + +### Naming pages + +If you create a new `.md` file, use the intended topic title as the name of the file. +The name you specify defines the UR, so it should be descriptive but not too long. +Replace spaces between words with a hyphen (-). +For example, use files names that look like this: + +- `create-a-new-pplication.md` - `new-version-pact.mdx` -Incorrect file name: +Not file names that look like this: - `newDOCSApplication.md` - `new_pact_version.ts` - `language reference.tsx` -### Frontmatter +### Specifying frontmatter -Every `.md` file should start with some meta data about the document. This is -called the frontmatter. For the docs application it looks something like this: +Every Markdown file includes a **frontmatter** section with some metadata about the document. +The frontmatter is always defined at the start of the file before any of the topic content. +For the docs web application, the frontmatter looks something like this: ```yaml --- -title: New docs application +title: Short topic title subTitle: It's new! -description: The new documentation website is better than ever -menu: New docs -label: New docs +description: Provides a brief description of the content of this page. +menu: Nav section +label: Nav title editLink: https://github.com/kadena-community/kadena.js/edit/main/packages/tools/cookbook/README.md publishDate: 1977-10-13 headerImage: /assets/blog/2020/1_b97oiC8M_ePx83B-PW0Cfg.webp -author: He-man -authorId: h.man -layout: blog +author: Author name +authorId: AuthorID +layout: Layout type --- ``` -Lets go over them 1 by 1. -`title`: the title of the document -`subTitle`: not required. Only used when on landing page layout. `description`: -a short description on what the page is about. This will be used as meta data -for SEO, but can also be used as an excerpt in the search results. -`menu`: the name used in the side or header menu's. -`label`: the name used in the breadcrumbs. -`editLink`: this is the place where the actual document lives. This particular -`md` file has been imported from somewhere else. The editlink is used at almost -every page, at the bottom. It will show a link to everyone visiting the page. -And they can create a PR with changes. `publishDate`: not required. only used -for blogchain, at the moment. And used to show the user what date the article -was first published. -`headerImage`: not required. only used for the blogchain as the main header on -top of the article. -`author`: _depricated_! not required. for blogchain we used to JUST show the -author name. -`authorID`: not required. replaced the above `author` field. The ID then reads -the author info from the `./src/data/authors.json` -`layout`: checks what layout the page will use to show the data. -`tags`: not required. An Array of strings that clarify what the content is -about. It is shown on blogchain pages, but is also used in the search indexing +| Keyword | Description +| ------- | ----------- +| `title` | Specifies the user-face title of the topic. It should match the file name. +| `subTitle`| Specifies a subtitle for the topic. It's only used in the landing page layout. +| `description`| Specifies a short description on what the page is about. This information is used as metadata for SEO and can be used as an excerpt in the search results. +| `menu` | Specifies the name used in the side or header menus. +| `label` | Specifies the name used in the breadcrumbs. +| `editLink` | Specifies the location of the content for the page. In this example, the content has been imported from somewhere else. The `editlink` is used at the bottom of almost every page to show a link for editing to everyone who visits the page to enable content changes from external contributors. The `editLink` is added to the frontmatter at runtime or when doc is imported from outside the package. +| `publishDate` | Specifies the date an article was first published. It's only used for BlogChain articles. +| `headerImage` | Specifies an image to use at the top of an article. It's only used for the BlogChain main header. +| `author` | Deprecated. +| `authorID` | Replaces the `author` field for BlogChain articles using the information from the `./src/data/authors.json` file. +| `layout` | Checks what layout the page will use to show the data. +| `tags` | Specifies an array of strings to clarify what the content is about. It's used for BlogChain articles and in the search indexing to get better search results. -### Edit link +### Adding images -For the documentation website we want the community to help out. It would be -great if they help out improving the documentation. Whether it is spelling -mistakes or clarifying sections. -The `editLink` frontmatter property, when available, will show an `edit page` -button at the bottom of the screen. This will send the user to the appropriate -github repo page where they can edit and create a PR with their changes. The -`editLink` will be added to the frontmatter on runtime or, when the doc is -imported from outside the package, it will be added during import. - -### Assets - -Assets like images can be saved in the following folder `/public/assets`. +You can add images—like diagrams and screenshots—in the following folder `/public/assets`. You can make as many subfolders as you see fit. -### H1 - -Every page's content should also start with an `h1` header. -If the `h1` header does not exist, the build scripts will give you a warning. +### Selecting a layout -### Layout +Pages can use different layouts to address different content requirements: -There are a couple of different layouts that can be used in the application. -`full`, `landing`, `blog`, `home` and `redocly`. +| Layout keyword | Description +| -------------- | ----------- +| `full` | Use the `full` layout with the left and right side menus for the most content pages. +| `landing` | Use the `landing` layout for section introductions that require more navigation and less content. +| `blog` | Use the `blog` layout for blog post articles. +| `home` | Use the `home` layout for top-level landing pages with multiple sections and the site home page. +| `redocly` | Use the `redocly` layout for generated swagger API output. -#### Full layout +#### Full layout example -![the layout](./public/assets/layout_full.png) Most pages will use this layout. -It has the left sidemenu and a table of content on the right. And it has the -most room for the actual content. +![Full](./public/assets/layout_full.png) -#### Landing layout +#### Landing layout example -![the layout](./public/assets/layout_landing.png) If a section needs a special -page landing page, to give it a bit more visibility we can use the landing -layout. -It has a large header that uses the `title` and `subTitle` from the frontmatter. +![the layout](./public/assets/layout_landing.png) -#### Blog layout +#### Blog layout example -![the layout](./public/assets/layout_blog.png) This layout is actually only used -for blog posts. It shows the large `headerImage` from the frontmatter, if -available. -It also shows the author info and `tags` from the frontmatter, if available. -Itdoes not have any sidemenus. +![the layout](./public/assets/layout_blog.png) -#### Redocly layout +#### Redocly layout example -![the layout](./public/assets/layout_redocly.png) Only used for pages that show -swagger API info. Not to be used for other documentation. +![the layout](./public/assets/layout_redocly.png) Only -#### Home layout +#### Home layout example -![the layout](./public/assets/layout_home.png) The `home` layout is not really -used together with `md` files. It is only used for landing pages of sections and -the actual home page. -It has a header that needs to be custom made for that page and we can do with -the rest of the layout what ever we want. +![the layout](./public/assets/layout_home.png) ## Moving pages around -Moving a page to another place in the tree is as simple as moving a file -somewhere inside the `src/pages` directory. -When the build then runs it is automatically is put in the correct position. -**Important:** +Moving a page to another place in the tree is as simple as moving a file somewhere inside the `src/pages` directory. +When the build runs, the page is automatically is put in the correct position. +However, keep in mind that renaming a file changes its URL and can have the following consequences: -- Renaming a file will ALSO change the URL. -- It could be that some internal links are now broken. You will get a warning +- Internal links might be broken. You will get a warning from the build scripts. -- It could be that some external websites were linking to this page and will now - get a 404. - - Please check analytics how many visits does this page get? - - If the page gets a lot of visits you can at a 301 redirect in - `next.confing.mjs`. - This will redirect all the old links to the new URL. - -## Imported docs - -Most of the documentation files live in the docs package and can be editted in -place as described. But there are also documentation files that live outside of -this package and are maintained in other packages or repos. These are then -imported and copied in their correct position during build time. -If you have ran the build script once you can see them in your `src/pages` tree. -If you make changes in these files they will be over written the next time you -make a build. - -So how do you know if this is an imported file and how can you make changes to -them? In these files there will be a frontmatter property called `editLink`. -When this property exists, this means that this is an imported document. And the -link will be the place where you can edit this particular file. - -### Multipage import - -Some docs, that are imported, are enourmously lengthy pages that are just to big -to show on 1 page. There we can say, during the import, that it needs to be -broken up. This is done automatically by checking `h2` headers. Every `h2` -header will now be the start of a new page. +- External pages or websites linking to the page might return 404 errors. + +Before renaming a file, check Google analytics to see how frequently the page is visited. +If the page gets a lot of views or visitors, define a 301 redirect in the `next.confing.mjs` file to redirect from the old URL to the new URL. + +## Importing content from external sources + +Most of the documentation files live in the `docs` package and can be edited directly in place. +However, some documentation files live outside of the `docs` package and are maintained in other packages or repositories. +Build scripts import and copy external documentation files into their correct position during the build. +After you run the build script once, the imported files are visible in the `src/pages` subfolder. +If you make changes in these files locally, your changes are overwritten the next time you run a build. + +If a file has the `editLink` frontmatter property, go to the location specified by this property to edit the file. + +### Multi-page import + +Some imported files are just too big to display as a single page. +These files are automatically broken up into multiple pages during the import process by checking the `h2` headings. +For these files, every `h2` heading is the start of a new page. The `editLink` frontmatter prop is the same for all these pages. ## Checking documentation validity -To check that all the files are valid and ready to build, but you don't want to -run the complete build run: +If you want to check that all the files are valid and ready to build without run the complete build, run the following command: ```bash pnpm build:scripts @@ -306,46 +296,23 @@ pnpm build:scripts ## Build scripts -There are a couple of build scripts running just before the site is put live. -These scripts help us with importing some docs, identifying issues with the -markdown files etc. - -`importAllReadmes.mjs` -This script will import some documentation from other packages of this repo. - -`createDocsTree.mjs` -This will create a large `json` file with the complete menu structure of the -whole app, together with some extra meta data. This file is super useful in the -app. For instance in finding the next and previous page, so we can use that at -the bottom of the page for easy navigation. - -`createSpecs.mjs` This creates the `json` files for the swagger-like pages for -pact and chainweb api documentation. - -`detectBrokenLinks.mjs` This will walk through all the documentation and check -all the internal links. To check if they are pointing to an actual file. This -will prevent 404's in our page when documentation is removed or moved to a -different menu/folder. -It will also check for certain domains that are not allowed anymore. Think about -`pact-language.readthedocs.io` or `medium.com/kadena-io`. Also it will rename -some links (from documentation that was imported) from https://docs.kadena.io to -internal links. +To help a build run smoothly by importing files and identifying issues like broken links or errors in Markdown, the following build scripts run before the site goes live: -`checkForHeaders.mjs` -Checks that every page uses at least an h1 header at the top of the page. -Important for SEO. +- `importAllReadmes.mjs` imports documentation from other packages in the current repo. +- `createDocsTree.mjs` create a large `json` file with the complete menu structure of the whole application, together with some extra metadata. This file is used for navigational features such as finding the next and previous pages for navigation. +- `createSpecs.mjs` creates the `json` files for the swagger-like pages for Pact and Chainweb API documentation. +- `detectBrokenLinks.mjs` checks all of the internal documentation links to verify that they are pointing to a file and prevent 404 errors. + This script also checks for domains that aren't used anymore, such as `pact-language.readthedocs.io` and `medium.com/kadena-io`. + The script renames some links from https://docs.kadena.io to internal links. +- `checkForHeaders.mjs` checks that every page uses at least an h1 header at the top of the page. Important for SEO. +- `checkAuthors.mjs` checks that blog posts have valid author information. +- `createSitemap.mjs` creates a sitemap of all the pages and creates a `sitemap.xml`. + This file is later imported by search engines to know what is needed to be crawled. Important for SEO. +- `copyFavIcons.mjs` copies all the favicons from the `/common/images/icons` package in the monorepo. -`checkAuthors.mjs` -Blog posts have author information. This script checks that this author -information is valid for our website. - -`createSitemap.mjs` -Creates a sitemap of all the pages and creates a `sitemap.xml`. -This file is later imported by search engines to know what is needed to be -craweled. Important for SEO. +## Adding issues -`copyFavIcons.mjs` -copy all the fav icons from `/common/images/icons` package in the monorepo. +If there are any issues with the docs or you suggestions for improvements, submit an [issue](https://github.com/kadena-community/kadena.js/issues). ## Cli @@ -354,8 +321,3 @@ The CLI is a TODO. - bootstrap a page - run build scripts more fine-grained (only the import scripts for example) - can we do something like 'docs-prettier'? - -## Adding issues - -If there are any issues with the docs, or you see room for improvements, you can add -stories to: https://github.com/kadena-community/kadena.js/issues From b7867d1a2c0a01938f70ecb001ee0ae1980b9d9c Mon Sep 17 00:00:00 2001 From: Lisa Gunn Date: Mon, 6 Nov 2023 14:36:13 -0800 Subject: [PATCH 3/7] Clean up around screenshots, adding issues --- packages/apps/docs/README.md | 42 +++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 13 deletions(-) diff --git a/packages/apps/docs/README.md b/packages/apps/docs/README.md index 48af79ebca..f5d7c29f56 100644 --- a/packages/apps/docs/README.md +++ b/packages/apps/docs/README.md @@ -230,33 +230,49 @@ Pages can use different layouts to address different content requirements: | Layout keyword | Description | -------------- | ----------- -| `full` | Use the `full` layout with the left and right side menus for the most content pages. -| `landing` | Use the `landing` layout for section introductions that require more navigation and less content. -| `blog` | Use the `blog` layout for blog post articles. | `home` | Use the `home` layout for top-level landing pages with multiple sections and the site home page. +| `landing` | Use the `landing` layout for section introductions that require more navigation and less content. +| `full` | Use the `full` layout with the left and right side menus for the most content pages. | `redocly` | Use the `redocly` layout for generated swagger API output. +| `blog` | Use the `blog` layout for blog post articles. -#### Full layout example +#### Home layout example + +The `home` layout use TypeScript and React instead of Markdown. +The text displayed is hardcoded. +The header and layout are customized for the page. -![Full](./public/assets/layout_full.png) +![Home layout](./public/assets/layout_home.png) #### Landing layout example -![the layout](./public/assets/layout_landing.png) +Section-level `landing` pages are similar to the `home` page. +They can provide a visual entry point to a large content set. +The layout uses the `title` and `subTitle` from the frontmatter. -#### Blog layout example +![Landing layout](./public/assets/layout_landing.png) + +#### Full layout example + +Most content pages use this layout with left peer and child navigation and a _On this page_ content on the right. -![the layout](./public/assets/layout_blog.png) +![Full layout](./public/assets/layout_full.png) #### Redocly layout example -![the layout](./public/assets/layout_redocly.png) Only +The `redocly` layout should only be used for swagger API pages. -#### Home layout example +![Redocly layout](./public/assets/layout_redocly.png) + +#### Blog layout example + +The `blog` layout should only be used for blog post articles. +It shows the large `headerImage` from the frontmatter, if available. +It also shows the `author` and `tags` from the frontmatter, if available. -![the layout](./public/assets/layout_home.png) +![Blog layout](./public/assets/layout_blog.png) -## Moving pages around +## Renaming and moving pages Moving a page to another place in the tree is as simple as moving a file somewhere inside the `src/pages` directory. When the build runs, the page is automatically is put in the correct position. @@ -312,7 +328,7 @@ To help a build run smoothly by importing files and identifying issues like brok ## Adding issues -If there are any issues with the docs or you suggestions for improvements, submit an [issue](https://github.com/kadena-community/kadena.js/issues). +If you find issues with the documentation content or format or have suggestions for improvement, submit an [issue](https://github.com/kadena-community/kadena.js/issues). ## Cli From bc36886ee04d386a256d966774ea5564d4828532 Mon Sep 17 00:00:00 2001 From: Lisa Gunn Date: Mon, 6 Nov 2023 14:36:13 -0800 Subject: [PATCH 4/7] Clean up around screenshots, adding issues --- packages/apps/docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/apps/docs/README.md b/packages/apps/docs/README.md index f5d7c29f56..8c11d3d2f6 100644 --- a/packages/apps/docs/README.md +++ b/packages/apps/docs/README.md @@ -172,7 +172,7 @@ The name you specify defines the UR, so it should be descriptive but not too lon Replace spaces between words with a hyphen (-). For example, use files names that look like this: -- `create-a-new-pplication.md` +- `create-a-new-application.md` - `new-version-pact.mdx` Not file names that look like this: From 6c12ec505e41cda73548874ac11854cbc6954f46 Mon Sep 17 00:00:00 2001 From: Lisa Gunn Date: Mon, 6 Nov 2023 14:42:48 -0800 Subject: [PATCH 5/7] Typo --- packages/apps/docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/apps/docs/README.md b/packages/apps/docs/README.md index 8c11d3d2f6..bf5ab155f7 100644 --- a/packages/apps/docs/README.md +++ b/packages/apps/docs/README.md @@ -336,4 +336,4 @@ The CLI is a TODO. - bootstrap a page - run build scripts more fine-grained (only the import scripts for example) -- can we do something like 'docs-prettier'? +- add formatting and spellcheck ('docs-prettier', remark plugins) From 9a2f0dfa496bae9115fd5aef713d92970cc0ef7f Mon Sep 17 00:00:00 2001 From: Lisa Gunn Date: Thu, 9 Nov 2023 15:17:45 -0800 Subject: [PATCH 6/7] Added changeset --- .changeset/nice-panthers-provide.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/nice-panthers-provide.md diff --git a/.changeset/nice-panthers-provide.md b/.changeset/nice-panthers-provide.md new file mode 100644 index 0000000000..d9ba63cd34 --- /dev/null +++ b/.changeset/nice-panthers-provide.md @@ -0,0 +1,5 @@ +--- +'@kadena/docs': patch +--- + +Update instructions for contributing to documentation. From 4313dbb4667e394352038e4ceb89bd3426aa372d Mon Sep 17 00:00:00 2001 From: Steven Straatemans Date: Tue, 21 Nov 2023 09:32:24 +0100 Subject: [PATCH 7/7] build --- packages/apps/docs/README.md | 335 ++++++++++++++++++++--------------- 1 file changed, 195 insertions(+), 140 deletions(-) diff --git a/packages/apps/docs/README.md b/packages/apps/docs/README.md index bf5ab155f7..1a92c1b92e 100644 --- a/packages/apps/docs/README.md +++ b/packages/apps/docs/README.md @@ -1,36 +1,47 @@ --- title: Contribute to Kadena documentation -description: Follow this guide to learn how you can contribute changes to Kadena documentation. +description: + Follow this guide to learn how you can contribute changes to Kadena + documentation. keywords: - developer documentation - Kadena blockchain --- -We encourage everyone with an interest in improving Kadena documentation to contribute content, submit issues, and suggest changes. -This guide describes how you can make changes to the documentation website directly by editing source files or indirectly by requesting updates. -You can follow these instructions whether you are an internal or external contributor. +We encourage everyone with an interest in improving Kadena documentation to +contribute content, submit issues, and suggest changes. This guide describes how +you can make changes to the documentation website directly by editing source +files or indirectly by requesting updates. You can follow these instructions +whether you are an internal or external contributor. ## Before you begin To follow the steps in this guide, verify the following basic requirements: -- You have a code editor, a GitHub account, and experience using command-line programs, including `git` commands and command line options. -- You are familiar with using Markdown to add formatting elements to plain text documents. - For information about using Markdown, see the [Markdown Guide](https://www.markdownguide.org/). +- You have a code editor, a GitHub account, and experience using command-line + programs, including `git` commands and command line options. +- You are familiar with using Markdown to add formatting elements to plain text + documents. For information about using Markdown, see the + [Markdown Guide](https://www.markdownguide.org/). - You have the `pnpm` package manager installed. - - Depending on your development environment, you can install `pnpm` using a standalone script or using a package manager. - For example, you can run the command `brew install pnpm` or `npm install --global pnpm` to install `pnpm` on your local computer. - For more information about installing `pnpm` on different operating systems, see [Installation](https://pnpm.io/installation). - - Run `pnpm --version` to verify that you have `pnpm` installed and the version you are running. -- You have run `pnpm setup` to add pnpm to your PATH environment variable and updated your terminal to use the new PATH. + Depending on your development environment, you can install `pnpm` using a + standalone script or using a package manager. For example, you can run the + command `brew install pnpm` or `npm install --global pnpm` to install `pnpm` + on your local computer. For more information about installing `pnpm` on + different operating systems, see [Installation](https://pnpm.io/installation). + + Run `pnpm --version` to verify that you have `pnpm` installed and the version + you are running. + +- You have run `pnpm setup` to add pnpm to your PATH environment variable and + updated your terminal to use the new PATH. ## Set up a local development environment -To set up a local development environment for contributing to Kadena documentation: +To set up a local development environment for contributing to Kadena +documentation: 1. Open a terminal shell on your computer. @@ -40,109 +51,130 @@ To set up a local development environment for contributing to Kadena documentati git clone https://github.com/kadena-community/kadena.js.git ``` - This command clones the entire public repository for the TypeScript and JavaScript tools that enable you to interact with the Kadena ecosystem, including the documentation engine and user interface components. + This command clones the entire public repository for the TypeScript and + JavaScript tools that enable you to interact with the Kadena ecosystem, + including the documentation engine and user interface components. + +1. Change to the root of the `kadena-js` repository by running the following + command: -2. Change to the root of the `kadena-js` repository by running the following command: - ```code cd kadena.js ``` -3. Install the workspace dependencies by running the following command: +1. Install the workspace dependencies by running the following command: ```code pnpm install ``` - This command installs all of the workspace dependencies used to build the documentation as a web application, including shared user interface components. + This command installs all of the workspace dependencies used to build the + documentation as a web application, including shared user interface + components. +1. Install the `turbo` virtualization software by running the following command: -4. Install the `turbo` virtualization software by running the following command: - ``` pnpm install --global turbo ``` - After you run this command, your local workspace has everything you need to build the documentation locally. + After you run this command, your local workspace has everything you need to + build the documentation locally. + +1. Change to the root of the `docs` application directory by running the + following command: -5. Change to the root of the `docs` application directory by running the following command: - ```code cd kadena.js/packages/apps/docs ``` - - If you explore the contents of the `docs` directory, you'll see the files and subfolders used to build the documentation as a web application. - To contribute to documentation, you typically only need to work in the `/src/pages` folder and its subfolders and individual pages. - The `/src/pages` folder includes files and subfolders that define the structure of the content and the operation of the application. - For example: + + If you explore the contents of the `docs` directory, you'll see the files and + subfolders used to build the documentation as a web application. To + contribute to documentation, you typically only need to work in the + `/src/pages` folder and its subfolders and individual pages. The `/src/pages` + folder includes files and subfolders that define the structure of the content + and the operation of the application. For example: - `/api` contains scripts to interact with the website using REST API calls. - `/authors` contains scripts to capture blog post authors. - `/blogchain` maintains the archive of blog post articles. - - `/build` contains sub-folders and Markdown files with information for builders. - - `/chainweb` contains a script to include Chainweb documentation that is generated automatically in the website. + - `/build` contains sub-folders and Markdown files with information for + builders. + - `/chainweb` contains a script to include Chainweb documentation that is + generated automatically in the website. - `/contribute` contains documentation related to community activities. - `/help` contains a placeholder for displaying help topics. - - `/kadena` contains sub-folders and Markdown files with information about Kadena, including core concepts and terminology. - - `/marmalade` contains sub-folders and Markdown files with information about Marmalade, including architecture and metadata. - - `/pact` contains sub-folders and Markdown files with information about the PACT language, including tutorials, examples, and reference. - - `/search` contains the script used to search for information in the application. + - `/kadena` contains sub-folders and Markdown files with information about + Kadena, including core concepts and terminology. + - `/marmalade` contains sub-folders and Markdown files with information about + Marmalade, including architecture and metadata. + - `/pact` contains sub-folders and Markdown files with information about the + PACT language, including tutorials, examples, and reference. + - `/search` contains the script used to search for information in the + application. - `/tags` contains scripts to capture blog post tags. - - Within these folders, the Markdown files—files with the `md` or `mdx` extension—contain the documentation content. - After you explore these folders, create a local working branch of the repository for your contribution. -6. Create a local branch with a prefix that identifies you as the author and a branch name that describes the content you intend to add or change. - For example, if your git handle is `lola-pistola` and you are fixing a typo in the kadena folder, you might create a branch like this: + Within these folders, the Markdown files—files with the `md` or `mdx` + extension—contain the documentation content. After you explore these folders, + create a local working branch of the repository for your contribution. + +1. Create a local branch with a prefix that identifies you as the author and a + branch name that describes the content you intend to add or change. For + example, if your git handle is `lola-pistola` and you are fixing a typo in + the kadena folder, you might create a branch like this: ```code git switch -c lola-pistola/typo-kadena-kda-concepts ``` - + ## Start a local development server -As you make changes to the content in your local branch, it's helpful to see how the changes will be -rendered when the documentation is published. +As you make changes to the content in your local branch, it's helpful to see how +the changes will be rendered when the documentation is published. -You can use `pnpm dev` to run a local development server that detects changes to the documentation and displays them automatically in the browser. +You can use `pnpm dev` to run a local development server that detects changes to +the documentation and displays them automatically in the browser. To start the development server in your local environment: -1. Open a terminal shell and switch to your working branch, if necessary. - For example: - +1. Open a terminal shell and switch to your working branch, if necessary. For + example: + ```code git switch lola-pistola/typo-kadena-kda-concepts ``` 1. Build the docs application by running the following command: - + ``` turbo run build --filter @kadena/docs^... ``` -2. Change to the `docs` application directory by running the following command: - +1. Change to the `docs` application directory by running the following command: + ```code cd kadena.js/packages/apps/docs ``` - -3. Start the development server by running the following command: - + +1. Start the development server by running the following command: + ```code pnpm dev ``` - This step imports files from multiple locations and can take some time to complete. + This step imports files from multiple locations and can take some time to + complete. + +1. Open a web browser and navigate to the documentation using the URL + `localhost:3000`. -4. Open a web browser and navigate to the documentation using the URL `localhost:3000`. - This step compiles the application and displays the top-level landing page. ## Structure content using folders and pages -The top-level landing page—including the text and curated links—is defined in the file `packages/apps/docs/src/pages/index.tsx`. -Currently, the top navigation header has the following top-level sections: +The top-level landing page—including the text and curated links—is defined in +the file `packages/apps/docs/src/pages/index.tsx`. Currently, the top navigation +header has the following top-level sections: - Kadena - Build @@ -152,14 +184,16 @@ Currently, the top navigation header has the following top-level sections: - Contribute - BlogChain -These top navigation links correspond to folders in the `src/pages` folder. -The landing page for each section also contains hard-coded text in the index.tsx file for that section. -For example, the Build section landing page is `packages/apps/docs/src/pages/build/index.tsx`. -Subsections within each top-level folder are grouped into folders and each folder has an `index.md` file for its first page of content. +These top navigation links correspond to folders in the `src/pages` folder. The +landing page for each section also contains hard-coded text in the index.tsx +file for that section. For example, the Build section landing page is +`packages/apps/docs/src/pages/build/index.tsx`. Subsections within each +top-level folder are grouped into folders and each folder has an `index.md` file +for its first page of content. -You can add pages to the existing structure to add a topic to the current information architecture. -The navigational structure can be up to three levels deep. -For example: +You can add pages to the existing structure to add a topic to the current +information architecture. The navigational structure can be up to three levels +deep. For example: - Top level (1) folder: Build - Second level (2) folder: Cookbooks @@ -167,10 +201,10 @@ For example: ### Naming pages -If you create a new `.md` file, use the intended topic title as the name of the file. -The name you specify defines the UR, so it should be descriptive but not too long. -Replace spaces between words with a hyphen (-). -For example, use files names that look like this: +If you create a new `.md` file, use the intended topic title as the name of the +file. The name you specify defines the UR, so it should be descriptive but not +too long. Replace spaces between words with a hyphen (-). For example, use files +names that look like this: - `create-a-new-application.md` - `new-version-pact.mdx` @@ -183,9 +217,10 @@ Not file names that look like this: ### Specifying frontmatter -Every Markdown file includes a **frontmatter** section with some metadata about the document. -The frontmatter is always defined at the start of the file before any of the topic content. -For the docs web application, the frontmatter looks something like this: +Every Markdown file includes a **frontmatter** section with some metadata about +the document. The frontmatter is always defined at the start of the file before +any of the topic content. For the docs web application, the frontmatter looks +something like this: ```yaml --- @@ -203,108 +238,114 @@ layout: Layout type --- ``` -| Keyword | Description -| ------- | ----------- -| `title` | Specifies the user-face title of the topic. It should match the file name. -| `subTitle`| Specifies a subtitle for the topic. It's only used in the landing page layout. -| `description`| Specifies a short description on what the page is about. This information is used as metadata for SEO and can be used as an excerpt in the search results. -| `menu` | Specifies the name used in the side or header menus. -| `label` | Specifies the name used in the breadcrumbs. -| `editLink` | Specifies the location of the content for the page. In this example, the content has been imported from somewhere else. The `editlink` is used at the bottom of almost every page to show a link for editing to everyone who visits the page to enable content changes from external contributors. The `editLink` is added to the frontmatter at runtime or when doc is imported from outside the package. -| `publishDate` | Specifies the date an article was first published. It's only used for BlogChain articles. -| `headerImage` | Specifies an image to use at the top of an article. It's only used for the BlogChain main header. -| `author` | Deprecated. -| `authorID` | Replaces the `author` field for BlogChain articles using the information from the `./src/data/authors.json` file. -| `layout` | Checks what layout the page will use to show the data. -| `tags` | Specifies an array of strings to clarify what the content is about. It's used for BlogChain articles and in the search indexing +| Keyword | Description | +| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `title` | Specifies the user-face title of the topic. It should match the file name. | +| `subTitle` | Specifies a subtitle for the topic. It's only used in the landing page layout. | +| `description` | Specifies a short description on what the page is about. This information is used as metadata for SEO and can be used as an excerpt in the search results. | +| `menu` | Specifies the name used in the side or header menus. | +| `label` | Specifies the name used in the breadcrumbs. | +| `editLink` | Specifies the location of the content for the page. In this example, the content has been imported from somewhere else. The `editlink` is used at the bottom of almost every page to show a link for editing to everyone who visits the page to enable content changes from external contributors. The `editLink` is added to the frontmatter at runtime or when doc is imported from outside the package. | +| `publishDate` | Specifies the date an article was first published. It's only used for BlogChain articles. | +| `headerImage` | Specifies an image to use at the top of an article. It's only used for the BlogChain main header. | +| `author` | Deprecated. | +| `authorID` | Replaces the `author` field for BlogChain articles using the information from the `./src/data/authors.json` file. | +| `layout` | Checks what layout the page will use to show the data. | +| `tags` | Specifies an array of strings to clarify what the content is about. It's used for BlogChain articles and in the search indexing | + to get better search results. ### Adding images -You can add images—like diagrams and screenshots—in the following folder `/public/assets`. -You can make as many subfolders as you see fit. +You can add images—like diagrams and screenshots—in the following folder +`/public/assets`. You can make as many subfolders as you see fit. ### Selecting a layout Pages can use different layouts to address different content requirements: -| Layout keyword | Description -| -------------- | ----------- -| `home` | Use the `home` layout for top-level landing pages with multiple sections and the site home page. -| `landing` | Use the `landing` layout for section introductions that require more navigation and less content. -| `full` | Use the `full` layout with the left and right side menus for the most content pages. -| `redocly` | Use the `redocly` layout for generated swagger API output. -| `blog` | Use the `blog` layout for blog post articles. +| Layout keyword | Description | +| -------------- | ------------------------------------------------------------------------------------------------- | +| `home` | Use the `home` layout for top-level landing pages with multiple sections and the site home page. | +| `landing` | Use the `landing` layout for section introductions that require more navigation and less content. | +| `full` | Use the `full` layout with the left and right side menus for the most content pages. | +| `redocly` | Use the `redocly` layout for generated swagger API output. | +| `blog` | Use the `blog` layout for blog post articles. | #### Home layout example -The `home` layout use TypeScript and React instead of Markdown. -The text displayed is hardcoded. -The header and layout are customized for the page. +The `home` layout use TypeScript and React instead of Markdown. The text +displayed is hardcoded. The header and layout are customized for the page. -![Home layout](./public/assets/layout_home.png) +![Home layout](./public/assets/layout_home.png) #### Landing layout example -Section-level `landing` pages are similar to the `home` page. -They can provide a visual entry point to a large content set. -The layout uses the `title` and `subTitle` from the frontmatter. +Section-level `landing` pages are similar to the `home` page. They can provide a +visual entry point to a large content set. The layout uses the `title` and +`subTitle` from the frontmatter. ![Landing layout](./public/assets/layout_landing.png) #### Full layout example -Most content pages use this layout with left peer and child navigation and a _On this page_ content on the right. +Most content pages use this layout with left peer and child navigation and a _On +this page_ content on the right. -![Full layout](./public/assets/layout_full.png) +![Full layout](./public/assets/layout_full.png) #### Redocly layout example The `redocly` layout should only be used for swagger API pages. -![Redocly layout](./public/assets/layout_redocly.png) +![Redocly layout](./public/assets/layout_redocly.png) #### Blog layout example -The `blog` layout should only be used for blog post articles. -It shows the large `headerImage` from the frontmatter, if available. -It also shows the `author` and `tags` from the frontmatter, if available. +The `blog` layout should only be used for blog post articles. It shows the large +`headerImage` from the frontmatter, if available. It also shows the `author` and +`tags` from the frontmatter, if available. ![Blog layout](./public/assets/layout_blog.png) ## Renaming and moving pages -Moving a page to another place in the tree is as simple as moving a file somewhere inside the `src/pages` directory. -When the build runs, the page is automatically is put in the correct position. -However, keep in mind that renaming a file changes its URL and can have the following consequences: +Moving a page to another place in the tree is as simple as moving a file +somewhere inside the `src/pages` directory. When the build runs, the page is +automatically is put in the correct position. However, keep in mind that +renaming a file changes its URL and can have the following consequences: -- Internal links might be broken. You will get a warning - from the build scripts. +- Internal links might be broken. You will get a warning from the build scripts. - External pages or websites linking to the page might return 404 errors. -Before renaming a file, check Google analytics to see how frequently the page is visited. -If the page gets a lot of views or visitors, define a 301 redirect in the `next.confing.mjs` file to redirect from the old URL to the new URL. +Before renaming a file, check Google analytics to see how frequently the page is +visited. If the page gets a lot of views or visitors, define a 301 redirect in +the `next.confing.mjs` file to redirect from the old URL to the new URL. ## Importing content from external sources -Most of the documentation files live in the `docs` package and can be edited directly in place. -However, some documentation files live outside of the `docs` package and are maintained in other packages or repositories. -Build scripts import and copy external documentation files into their correct position during the build. -After you run the build script once, the imported files are visible in the `src/pages` subfolder. -If you make changes in these files locally, your changes are overwritten the next time you run a build. +Most of the documentation files live in the `docs` package and can be edited +directly in place. However, some documentation files live outside of the `docs` +package and are maintained in other packages or repositories. Build scripts +import and copy external documentation files into their correct position during +the build. After you run the build script once, the imported files are visible +in the `src/pages` subfolder. If you make changes in these files locally, your +changes are overwritten the next time you run a build. -If a file has the `editLink` frontmatter property, go to the location specified by this property to edit the file. +If a file has the `editLink` frontmatter property, go to the location specified +by this property to edit the file. ### Multi-page import -Some imported files are just too big to display as a single page. -These files are automatically broken up into multiple pages during the import process by checking the `h2` headings. -For these files, every `h2` heading is the start of a new page. -The `editLink` frontmatter prop is the same for all these pages. +Some imported files are just too big to display as a single page. These files +are automatically broken up into multiple pages during the import process by +checking the `h2` headings. For these files, every `h2` heading is the start of +a new page. The `editLink` frontmatter prop is the same for all these pages. ## Checking documentation validity -If you want to check that all the files are valid and ready to build without run the complete build, run the following command: +If you want to check that all the files are valid and ready to build without run +the complete build, run the following command: ```bash pnpm build:scripts @@ -312,23 +353,37 @@ pnpm build:scripts ## Build scripts -To help a build run smoothly by importing files and identifying issues like broken links or errors in Markdown, the following build scripts run before the site goes live: - -- `importAllReadmes.mjs` imports documentation from other packages in the current repo. -- `createDocsTree.mjs` create a large `json` file with the complete menu structure of the whole application, together with some extra metadata. This file is used for navigational features such as finding the next and previous pages for navigation. -- `createSpecs.mjs` creates the `json` files for the swagger-like pages for Pact and Chainweb API documentation. -- `detectBrokenLinks.mjs` checks all of the internal documentation links to verify that they are pointing to a file and prevent 404 errors. - This script also checks for domains that aren't used anymore, such as `pact-language.readthedocs.io` and `medium.com/kadena-io`. - The script renames some links from https://docs.kadena.io to internal links. -- `checkForHeaders.mjs` checks that every page uses at least an h1 header at the top of the page. Important for SEO. +To help a build run smoothly by importing files and identifying issues like +broken links or errors in Markdown, the following build scripts run before the +site goes live: + +- `importAllReadmes.mjs` imports documentation from other packages in the + current repo. +- `createDocsTree.mjs` create a large `json` file with the complete menu + structure of the whole application, together with some extra metadata. This + file is used for navigational features such as finding the next and previous + pages for navigation. +- `createSpecs.mjs` creates the `json` files for the swagger-like pages for Pact + and Chainweb API documentation. +- `detectBrokenLinks.mjs` checks all of the internal documentation links to + verify that they are pointing to a file and prevent 404 errors. This script + also checks for domains that aren't used anymore, such as + `pact-language.readthedocs.io` and `medium.com/kadena-io`. The script renames + some links from https://docs.kadena.io to internal links. +- `checkForHeaders.mjs` checks that every page uses at least an h1 header at the + top of the page. Important for SEO. - `checkAuthors.mjs` checks that blog posts have valid author information. -- `createSitemap.mjs` creates a sitemap of all the pages and creates a `sitemap.xml`. - This file is later imported by search engines to know what is needed to be crawled. Important for SEO. -- `copyFavIcons.mjs` copies all the favicons from the `/common/images/icons` package in the monorepo. +- `createSitemap.mjs` creates a sitemap of all the pages and creates a + `sitemap.xml`. This file is later imported by search engines to know what is + needed to be crawled. Important for SEO. +- `copyFavIcons.mjs` copies all the favicons from the `/common/images/icons` + package in the monorepo. ## Adding issues -If you find issues with the documentation content or format or have suggestions for improvement, submit an [issue](https://github.com/kadena-community/kadena.js/issues). +If you find issues with the documentation content or format or have suggestions +for improvement, submit an +[issue](https://github.com/kadena-community/kadena.js/issues). ## Cli