Markdown Overview Buttons Tabs Footnotes Collapse ToC Navigation Formula Page-Specific Meta Custom Components
MIT License
Copyright © 2020
CONNECT-platform
The misc config property can be used to configure external integrations. CODEDOC
ships with integrations with GitHub and Gitter, respectively configurable via github
and gitter properties:
1linkimport { configuration } from '@codedoc/core';
2link
3link//...
4link
5linkexport const config = /*#__PURE__*/configuration({
6link //...
7link misc: {
8link github: {
9link user: 'johndoe', // --> name of the user on GitHub owning the repo
10link repo: 'my-project', // --> name of the repo on GitHub
11link action: 'Fork', // --> action of the GitHub button
12link count: false, // --> whether to show the `count` on the GitHub button
13link large: true, // --> whether to show a `large` GitHub button
14link standardIcon: false, // --> whether to use the GitHub icon on the GitHub button or use an action specific icon
15link },
16link gitter: {
17link room: 'johndoe/my-project' // --> id of the Gitter room for the project
18link }
19link },
20link //...
21link});
The GitHub integration includes the standard GitHub button in the header, a link to the repo in the footer
and GitHub search functionality. You can configure this integration via github property:
1linkimport { configuration } from '@codedoc/core';
2link
3link//...
4link
5linkexport const config = /*#__PURE__*/configuration({
6link //...
7link misc: {
8link github: {
9link user: 'johndoe', // --> name of the user on GitHub owning the repo
10link repo: 'my-project', // --> name of the repo on GitHub
11link action: 'Issue', // --> action of the GitHub button
12link count: true, // --> whether to show the `count` on the GitHub button
13link large: true, // --> whether to show a `large` GitHub button
14link standardIcon: true, // --> whether to use the GitHub icon on the GitHub button or use an action specific icon
15link },
16link //...
17link },
18link //...
19link});
user should be the username of the owner of the repository.repo should be the repository nameaction should be the action of the GitHub button in the header. It can be one of the following:'Download''Follow''Fork''Issue''Sponsor''Star' (which is the default)'Watch''UseThisTemplate'count is whether or not to display the action-specific count on the GitHub button. For example, if
action is 'Star', then count would be the number of stars the repository has. Defaults to true.large is whether or not to display a large style GitHub button (defaults to false).standardIcon is whether to use the standard GitHub icon on the button, or to use an action-specific icon.
Default is true (i.e. use the GitHub icon).If you are using a seperate repository for your documentation, you would want to configure the GitHub integration to point at your main repository, while having the GitHub search functionality look into your documentation repository.
Imagine your main repository is my-project and its documentation repository is my-project-docs, all owned
by the user johndoe.
STEP 1
Configure .codedoc/config.ts to point to my-project:
1linkimport { configuration } from '@codedoc/core';
2link
3link//...
4link
5linkexport const config = /*#__PURE__*/configuration({
6link //...
7link misc: {
8link github: {
9link user: 'johndoe',
10link repo: 'my-project',
11link //...
12link },
13link //...
14link },
15link //...
16link});
STEP 2
Configure the search functionality (via .codedoc/content/index.tsx) to use my-project-docs instead:
1linkimport { RendererLike } from '@connectv/html';
2linkimport { File } from 'rxline/fs';
3linkimport { Page, Meta, ContentNav, Fonts, ToC, GithubSearch$ } from '@codedoc/core/components';
4link
5linkimport { config } from '../config';
6linkimport { Header } from './header';
7linkimport { Footer } from './footer';
8link
9link
10linkexport function content(_content: HTMLElement, toc: HTMLElement, renderer: RendererLike<any, any>, file: File<string>) {
11link return (
12link <Page title={config.page.title.extractor(_content, config, file)}
13link favicon={config.page.favicon}
14link meta={<Meta {...config.page.meta}/>}
15link fonts={<Fonts {...config.page.fonts}/>}
16link
17link scripts={config.page.scripts}
18link stylesheets={config.page.stylesheets}
19link
20link header={<Header {...config}/>}
21link footer={<Footer {...config}/>}
22link toc={
23link <ToC search={
24link config.misc?.github ?
25link <GithubSearch$
26link repo="my-project-docs" // --> change this line
27link user={config.misc.github.user}
28link root={config.src.base}
29link pick={config.src.pick.source}
30link drop={config.src.drop.source}
31link /> : false
32link }>{toc}</ToC>
33link }>
34link {_content}
35link <ContentNav content={_content}/>
36link </Page>
37link )
38link}
The Gitter integration will include the Gitter side-car on your docs page, activatable via
the Community link in the footer (click on the Community link on the footer of this page
to see how it looks):
1linkimport { configuration } from '@codedoc/core';
2link
3link//...
4link
5linkexport const config = /*#__PURE__*/configuration({
6link //...
7link misc: {
8link gitter: {
9link room: 'johndoe/my-project' // --> id of the Gitter room for the project
10link }
11link },
12link //...
13link});
I you are deploying on Vercel, the default routing would not work out of the box.
To fix that, you need to configure Vercel accordingly (in vercel.json at the root of your project):
1link{
2link "cleanUrls": true
3link}