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. diff --git a/packages/apps/docs/README.md b/packages/apps/docs/README.md index 645c817a0d..1a92c1b92e 100644 --- a/packages/apps/docs/README.md +++ b/packages/apps/docs/README.md @@ -1,257 +1,389 @@ -# Contribute to the docs +--- +title: Contribute to Kadena documentation +description: + Follow this guide to learn how you can contribute changes to Kadena + documentation. +keywords: + - developer documentation + - Kadena blockchain +--- -In this document you can find all the info you need to contribute to the docs. +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. -## Structure of the app +## Before you begin -When you have cloned the repo and found this package, you are almost good to go. -run the following +To follow the steps in this guide, verify the following basic requirements: -``` -pnpm install -``` +- 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/). -to run the app on `http://localhost:3000` +- You have the `pnpm` package manager installed. -``` -pnpm dev -``` + 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: + +1. Open a terminal shell on your computer. + +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 engine and user interface components. + +1. Change to the root of the `kadena-js` repository by running the following + command: + + ```code + cd kadena.js + ``` + +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. + +1. 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. + +1. 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. + - `/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. + +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 -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. +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. -Some things to consider: +You can use `pnpm dev` to run a local development server that detects changes to +the documentation and displays them automatically in the browser. -- `/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. +To start the development server in your local environment: -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 +1. Open a terminal shell and switch to your working branch, if necessary. For + example: -## Adding a page + ```code + git switch lola-pistola/typo-kadena-kda-concepts + ``` -A new page can be placed anywhere in the `src/pages` tree. -Be aware that the tree can not be deeper than **3** folders. +1. Build the docs application by running the following command: -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/). + ``` + turbo run build --filter @kadena/docs^... + ``` -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: +1. Change to the `docs` application directory by running the following command: -- `new-docs-application.md` + ```code + cd kadena.js/packages/apps/docs + ``` + +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. + +1. 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: + +- Kadena +- Build +- Pact +- Chainweb +- Marmalade +- 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. + +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 +- 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-application.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. +You can add images—like diagrams and screenshots—in the following folder +`/public/assets`. You can make as many subfolders as you see fit. -### Assets +### Selecting a layout -Assets like images can be saved in the following folder `/public/assets`. -You can make as many subfolders as you see fit. +Pages can use different layouts to address different content requirements: -### H1 +| 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. | -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. +#### Home layout example -### Layout +The `home` layout use TypeScript and React instead of Markdown. The text +displayed is hardcoded. The header and layout are customized for the page. -There are a couple of different layouts that can be used in the application. -`full`, `landing`, `blog`, `home` and `redocly`. +![Home layout](./public/assets/layout_home.png) -#### Full layout +#### Landing 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. +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 +![Landing layout](./public/assets/layout_landing.png) -![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. +#### Full layout example -#### Blog layout +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) 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. +![Full layout](./public/assets/layout_full.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 `redocly` layout should only be used for swagger API pages. -#### Home layout +![Redocly layout](./public/assets/layout_redocly.png) -![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. +#### Blog layout example -## Moving pages around +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 then runs it is automatically is put in the correct position. -**Important:** - -- Renaming a file will ALSO change the URL. -- It could be that some internal links are now 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. -The `editLink` frontmatter prop is the same for all these pages. +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: -## Checking documentation validity +- 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. -To check that all the files are valid and ready to build, but you don't want to -run the complete build run: +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. -```bash -pnpm build:scripts -``` +## Importing content from external sources -## Build scripts +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. -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. +If a file has the `editLink` frontmatter property, go to the location specified +by this property to edit the file. -`importAllReadmes.mjs` -This script will import some documentation from other packages of this repo. +### Multi-page import -`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. +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. -`createSpecs.mjs` This creates the `json` files for the swagger-like pages for -pact and chainweb api documentation. +## 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: -`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. +```bash +pnpm build:scripts +``` -`checkForHeaders.mjs` -Checks that every page uses at least an h1 header at the top of the page. -Important for SEO. +## Build scripts -`checkAuthors.mjs` -Blog posts have author information. This script checks that this author -information is valid for our website. +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 -craweled. Important for SEO. +## Adding issues -`copyFavIcons.mjs` -copy all the fav icons from `/common/images/icons` package in the monorepo. +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 @@ -259,9 +391,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'? - -## 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 +- add formatting and spellcheck ('docs-prettier', remark plugins)