|
| 1 | +# Contribute to the docs |
| 2 | + |
| 3 | +In this document you can find all the info you need to contribute to the docs. |
| 4 | + |
| 5 | +## Structure of the app |
| 6 | + |
| 7 | +When you have cloned the repo and found this package, you are almost good to go. |
| 8 | +run the following |
| 9 | + |
| 10 | +``` |
| 11 | +pnpm install |
| 12 | +``` |
| 13 | + |
| 14 | +to run the app on `http://localhost:3000` |
| 15 | + |
| 16 | +``` |
| 17 | +pnpm dev |
| 18 | +``` |
| 19 | + |
| 20 | +Most of the files are just there for the application it self. |
| 21 | +For writing the actual docs, the only real important folder is `/src/pages`. |
| 22 | +This is basically the root of the application. The folders create the menu |
| 23 | +structure you can find in the application it self. Most of the folders in the |
| 24 | +`/src/pages` folder are also in the mainheader menu. |
| 25 | + |
| 26 | +Some things to consider: |
| 27 | + |
| 28 | +- `/api` this is not a place to add documentation. This folder is used by the |
| 29 | + application itself, to do REST API calls. |
| 30 | +- `/search` is normally also not used to put documentation. Here you can find |
| 31 | + the files for the actual search of the application. |
| 32 | + |
| 33 | +All the other files (especially with the extension `md` or `mdx`) are the actual |
| 34 | +documentation files and you can do basically do anything with them |
| 35 | + |
| 36 | +## Adding a page |
| 37 | + |
| 38 | +A new page can be placed anywhere in the `src/pages` tree. |
| 39 | +Be aware that the tree can not be deeper than **3** folders. |
| 40 | + |
| 41 | +All the documentation is written in markdown. |
| 42 | +Markdown is a lightweight markup language that you can use to add formatting |
| 43 | +elements to plaintext text documents. You can learn more about |
| 44 | +[Markdown here](https://www.markdownguide.org/). |
| 45 | + |
| 46 | +Create a `.md` file. The name of the file is also the name of the URL. Make it a |
| 47 | +good one. Best is to make it the title of the document. For `spaces`, please use |
| 48 | +`-`. Correct file name: |
| 49 | + |
| 50 | +- `new-docs-application.md` |
| 51 | +- `new-version-pact.mdx` |
| 52 | + |
| 53 | +Incorrect file name: |
| 54 | + |
| 55 | +- `newDOCSApplication.md` |
| 56 | +- `new_pact_version.ts` |
| 57 | +- `language reference.tsx` |
| 58 | + |
| 59 | +### Frontmatter |
| 60 | + |
| 61 | +Every `.md` file should start with some meta data about the document. This is |
| 62 | +called the frontmatter. For the docs application it looks something like this: |
| 63 | + |
| 64 | +```yaml |
| 65 | +--- |
| 66 | +title: New docs application |
| 67 | +subTitle: It's new! |
| 68 | +description: The new documentation website is better than ever |
| 69 | +menu: New docs |
| 70 | +label: New docs |
| 71 | +editLink: https://github.com/kadena-community/kadena.js/edit/main/packages/tools/cookbook/README.md |
| 72 | +publishDate: 1977-10-13 |
| 73 | +headerImage: /assets/blog/2020/1_b97oiC8M_ePx83B-PW0Cfg.webp |
| 74 | +author: He-man |
| 75 | +authorId: h.man |
| 76 | +layout: blog |
| 77 | +--- |
| 78 | +``` |
| 79 | + |
| 80 | +Lets go over them 1 by 1. |
| 81 | +`title`: the title of the document |
| 82 | +`subTitle`: not required. Only used when on landing page layout. `description`: |
| 83 | +a short description on what the page is about. This will be used as meta data |
| 84 | +for SEO, but can also be used as an excerpt in the search results. |
| 85 | +`menu`: the name used in the side or header menu's. |
| 86 | +`label`: the name used in the breadcrumbs. |
| 87 | +`editLink`: this is the place where the actual document lives. This particular |
| 88 | +`md` file has been imported from somewhere else. The editlink is used at almost |
| 89 | +every page, at the bottom. It will show a link to everyone visiting the page. |
| 90 | +And they can create a PR with changes. `publishDate`: not required. only used |
| 91 | +for blogchain, at the moment. And used to show the user what date the article |
| 92 | +was first published. |
| 93 | +`headerImage`: not required. only used for the blogchain as the main header on |
| 94 | +top of the article. |
| 95 | +`author`: _depricated_! not required. for blogchain we used to JUST show the |
| 96 | +author name. |
| 97 | +`authorID`: not required. replaced the above `author` field. The ID then reads |
| 98 | +the author info from the `./src/data/authors.json` |
| 99 | +`layout`: checks what layout the page will use to show the data. |
| 100 | +`tags`: not required. An Array of strings that clarify what the content is |
| 101 | +about. It is shown on blogchain pages, but is also used in the search indexing |
| 102 | +to get better search results. |
| 103 | + |
| 104 | +### Edit link |
| 105 | + |
| 106 | +For the documentation website we want the community to help out. It would be |
| 107 | +great if they help out improving the documentation. Whether it is spelling |
| 108 | +mistakes or clarifying sections. |
| 109 | +The `editLink` frontmatter property, when available, will show an `edit page` |
| 110 | +button at the bottom of the screen. This will send the user to the appropriate |
| 111 | +github repo page where they can edit and create a PR with their changes. The |
| 112 | +`editLink` will be added to the frontmatter on runtime or, when the doc is |
| 113 | +imported from outside the package, it will be added during import. |
| 114 | + |
| 115 | +### Assets |
| 116 | + |
| 117 | +Assets like images can be saved in the following folder `/public/assets`. |
| 118 | +You can make as many subfolders as you see fit. |
| 119 | + |
| 120 | +### H1 |
| 121 | + |
| 122 | +Every page's content should also start with an `h1` header. |
| 123 | +If the `h1` header does not exist, the build scripts will give you a warning. |
| 124 | + |
| 125 | +### Layout |
| 126 | + |
| 127 | +There are a couple of different layouts that can be used in the application. |
| 128 | +`full`, `landing`, `blog`, `home` and `redocly`. |
| 129 | + |
| 130 | +#### Full layout |
| 131 | + |
| 132 | + Most pages will use this layout. |
| 133 | +It has the left sidemenu and a table of content on the right. And it has the |
| 134 | +most room for the actual content. |
| 135 | + |
| 136 | +#### Landing layout |
| 137 | + |
| 138 | + If a section needs a special |
| 139 | +page landing page, to give it a bit more visibility we can use the landing |
| 140 | +layout. |
| 141 | +It has a large header that uses the `title` and `subTitle` from the frontmatter. |
| 142 | + |
| 143 | +#### Blog layout |
| 144 | + |
| 145 | + This layout is actually only used |
| 146 | +for blog posts. It shows the large `headerImage` from the frontmatter, if |
| 147 | +available. |
| 148 | +It also shows the author info and `tags` from the frontmatter, if available. |
| 149 | +Itdoes not have any sidemenus. |
| 150 | + |
| 151 | +#### Redocly layout |
| 152 | + |
| 153 | + Only used for pages that show |
| 154 | +swagger API info. Not to be used for other documentation. |
| 155 | + |
| 156 | +#### Home layout |
| 157 | + |
| 158 | + The `home` layout is not really |
| 159 | +used together with `md` files. It is only used for landing pages of sections and |
| 160 | +the actual home page. |
| 161 | +It has a header that needs to be custom made for that page and we can do with |
| 162 | +the rest of the layout what ever we want. |
| 163 | + |
| 164 | +## Moving pages around |
| 165 | + |
| 166 | +Moving a page to another place in the tree is as simple as moving a file |
| 167 | +somewhere inside the `src/pages` directory. |
| 168 | +When the build then runs it is automatically is put in the correct position. |
| 169 | +**Important:** |
| 170 | + |
| 171 | +- Renaming a file will ALSO change the URL. |
| 172 | +- It could be that some internal links are now broken. You will get a warning |
| 173 | + from the build scripts. |
| 174 | +- It could be that some external websites were linking to this page and will now |
| 175 | + get a 404. |
| 176 | + - Please check analytics how many visits does this page get? |
| 177 | + - If the page gets a lot of visits you can at a 301 redirect in |
| 178 | + `next.confing.mjs`. |
| 179 | + This will redirect all the old links to the new URL. |
| 180 | + |
| 181 | +## Imported docs |
| 182 | + |
| 183 | +Most of the documentation files live in the docs package and can be editted in |
| 184 | +place as described. But there are also documentation files that live outside of |
| 185 | +this package and are maintained in other packages or repos. These are then |
| 186 | +imported and copied in their correct position during build time. |
| 187 | +If you have ran the build script once you can see them in your `src/pages` tree. |
| 188 | +If you make changes in these files they will be over written the next time you |
| 189 | +make a build. |
| 190 | + |
| 191 | +So how do you know if this is an imported file and how can you make changes to |
| 192 | +them? In these files there will be a frontmatter property called `editLink`. |
| 193 | +When this property exists, this means that this is an imported document. And the |
| 194 | +link will be the place where you can edit this particular file. |
| 195 | + |
| 196 | +### Multipage import |
| 197 | + |
| 198 | +Some docs, that are imported, are enourmously lengthy pages that are just to big |
| 199 | +to show on 1 page. There we can say, during the import, that it needs to be |
| 200 | +broken up. This is done automatically by checking `h2` headers. Every `h2` |
| 201 | +header will now be the start of a new page. |
| 202 | +The `editLink` frontmatter prop is the same for all these pages. |
| 203 | + |
| 204 | +## Checking documentation validity |
| 205 | + |
| 206 | +To check that all the files are valid and ready to build, but you don't want to |
| 207 | +run the complete build run: |
| 208 | + |
| 209 | +```bash |
| 210 | +pnpm build:scripts |
| 211 | +``` |
| 212 | + |
| 213 | +## Build scripts |
| 214 | + |
| 215 | +There are a couple of build scripts running just before the site is put live. |
| 216 | +These scripts help us with importing some docs, identifying issues with the |
| 217 | +markdown files etc. |
| 218 | + |
| 219 | +`importAllReadmes.mjs` |
| 220 | +This script will import some documentation from other packages of this repo. |
| 221 | + |
| 222 | +`createDocsTree.mjs` |
| 223 | +This will create a large `json` file with the complete menu structure of the |
| 224 | +whole app, together with some extra meta data. This file is super useful in the |
| 225 | +app. For instance in finding the next and previous page, so we can use that at |
| 226 | +the bottom of the page for easy navigation. |
| 227 | + |
| 228 | +`createSpecs.mjs` This creates the `json` files for the swagger-like pages for |
| 229 | +pact and chainweb api documentation. |
| 230 | + |
| 231 | +`detectBrokenLinks.mjs` This will walk through all the documentation and check |
| 232 | +all the internal links. To check if they are pointing to an actual file. This |
| 233 | +will prevent 404's in our page when documentation is removed or moved to a |
| 234 | +different menu/folder. |
| 235 | +It will also check for certain domains that are not allowed anymore. Think about |
| 236 | +`pact-language.readthedocs.io` or `medium.com/kadena-io`. Also it will rename |
| 237 | +some links (from documentation that was imported) from https://docs.kadena.io to |
| 238 | +internal links. |
| 239 | + |
| 240 | +`checkForHeaders.mjs` |
| 241 | +Checks that every page uses at least an h1 header at the top of the page. |
| 242 | +Important for SEO. |
| 243 | + |
| 244 | +`checkAuthors.mjs` |
| 245 | +Blog posts have author information. This script checks that this author |
| 246 | +information is valid for our website. |
| 247 | + |
| 248 | +`createSitemap.mjs` |
| 249 | +Creates a sitemap of all the pages and creates a `sitemap.xml`. |
| 250 | +This file is later imported by search engines to know what is needed to be |
| 251 | +craweled. Important for SEO. |
| 252 | + |
| 253 | +`copyFavIcons.mjs` |
| 254 | +copy all the fav icons from `/common/images/icons` package in the monorepo. |
| 255 | + |
| 256 | +## Cli |
| 257 | + |
| 258 | +The CLI is a TODO. |
| 259 | + |
| 260 | +- bootstrap a page |
| 261 | +- run build scripts more fine-grained (only the import scripts for example) |
| 262 | +- can we do something like 'docs-prettier'? |
| 263 | + |
| 264 | +## Adding issues |
| 265 | + |
| 266 | +If there are any issues with the docs, or you see room for improvements, you can add |
| 267 | +stories to: https://github.com/kadena-community/kadena.js/issues |
0 commit comments