Out of the box Gatsby Theme for creating documentation websites easily and quickly.
Features • Getting started • Docs • Contributing • License
## 🚀 Features - 📝 MDX for docs; - 🛣 Yaml-based sidebar navigation; - 📱 Responsive and mobile friendly; - 🖥 Code highlighting with [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) and [react-live](https://github.com/FormidableLabs/react-live) support; - 🥇 SEO (Sitemap, schema.org data, Open Graph and Twitter tags). - 📈 Google Analytics support; - 📄 Custom docs schema; - 🖱 Table of Contents; - ⚡️ Offline Support & WebApp Manifest; - and much more 🔥 ## ⚡️ Getting started 1. Create the website. ```sh npx gatsby new rocketdocs https://github.com/jpedroschmitz/gatsby-starter-rocketdocs ``` 2. Start developing. ```sh cd rocketdocs gatsby develop ``` 3. Are you ready for launch? 🚀 Your site is now running at `http://localhost:8000` ## 📄 Docs Looking for docs? Check our live demo and documentation [website](https://rocketdocs.netlify.app). ## ✨ Contributing Thanks for being interested in contributing! We’re so glad you want to help! Please take a little bit of your time and look at our [contributing guidelines](https://github.com/jpedroschmitz/rocketdocs/blob/main/.github/CONTRIBUTING.md) and our [code of conduct](https://github.com/jpedroschmitz/rocketdocs/blob/main/.github/CODE_OF_CONDUCT.md)! All type of contributions are welcome, such as bug fixes, issues or feature requests. ## 🗺 Changelog All notable changes to this project will be documented on the [CHANGELOG](https://github.com/jpedroschmitz/rocketdocs/blob/main/%40rocketseat/gatsby-theme-docs/CHANGELOG.md) file. ## 📝 License Licensed under the [MIT License](https://github.com/jpedroschmitz/rocketdocs/blob/main/%40rocketseat/gatsby-theme-docs/LICENSE). --- Made with 💜 by João Pedro ================================================ FILE: @rocketseat/gatsby-theme-docs/gatsby/wrapPageElement.js ================================================ /* eslint-disable */ import React from 'react'; import { MDXProvider } from '@mdx-js/react'; import Code from '../src/components/Code'; const preToCodeBlock = (preProps) => { if ( // children is code element preProps.children && // if children is actually a
preProps.children.type &&
preProps.children.type.name &&
preProps.children.type.name === 'code'
) {
// we have a situation
const {
children: codeString,
className = '',
...props
} = preProps.children.props;
const match = className.match(/language-([\0-\uFFFF]*)/);
return {
codeString: codeString.trim(),
className,
language: match != null ? match[1] : '',
...props,
};
}
return undefined;
};
const components = {
pre: (preProps) => {
const props = preToCodeBlock(preProps);
if (props) {
return {children}
),
};
export function wrapPageElement({ element }) {
return {element} ;
}
================================================
FILE: @rocketseat/gatsby-theme-docs/gatsby/wrapRootElement.js
================================================
/* eslint-disable */
import React from 'react';
import { ThemeProvider } from '@emotion/react';
import defaultTheme from '../src/styles/theme';
import GlobalStyle from '../src/styles/global';
export function wrapRootElement({ element }) {
return (
<>
);
}
================================================
FILE: @rocketseat/gatsby-theme-docs/gatsby-browser.js
================================================
export { wrapRootElement } from './gatsby/wrapRootElement';
export { wrapPageElement } from './gatsby/wrapPageElement';
================================================
FILE: @rocketseat/gatsby-theme-docs/gatsby-config.js
================================================
const withDefault = require('@rocketseat/gatsby-theme-docs-core/util/with-default');
module.exports = (options) => {
const themeOptions = withDefault(options);
return {
siteMetadata: {
defaultTitle: `Rocket Docs by João Pedro Schmitz`,
siteTitle: `Rocket Docs`,
siteTitleShort: `Rocket Docs`,
siteDescription: `Easy to use Gatsby Theme to create documentation websites`,
siteUrl: `https://rocketdocs.netlify.app`,
siteAuthor: `@jpedroschmitz`,
siteImage: `/banner.png`,
siteLanguage: `en`,
basePath: themeOptions.basePath,
docsPath: themeOptions.docsPath,
},
plugins: [
{
resolve: `gatsby-source-filesystem`,
options: {
name: `homepage`,
path: themeOptions.homePath || `${__dirname}/src/text`,
},
},
{
resolve: `@rocketseat/gatsby-theme-docs-core`,
options: themeOptions,
},
`gatsby-plugin-catch-links`,
`gatsby-plugin-emotion`,
`gatsby-plugin-react-helmet`,
].filter(Boolean),
};
};
================================================
FILE: @rocketseat/gatsby-theme-docs/gatsby-ssr.js
================================================
export { wrapRootElement } from './gatsby/wrapRootElement';
export { wrapPageElement } from './gatsby/wrapPageElement';
================================================
FILE: @rocketseat/gatsby-theme-docs/index.js
================================================
// beep
================================================
FILE: @rocketseat/gatsby-theme-docs/package.json
================================================
{
"name": "@rocketseat/gatsby-theme-docs",
"version": "4.0.1",
"main": "index.js",
"description": "Out of the box Gatsby Theme for creating documentation websites easily and quickly.",
"author": "João Pedro Schmitz (@jpedroschmitz)",
"license": "MIT",
"publishConfig": {
"access": "public"
},
"keywords": [
"documentation",
"open source",
"gatsby",
"gatsby-plugin",
"gatsby-theme",
"react",
"docs",
"mdx"
],
"homepage": "https://github.com/jpedroschmitz/rocketdocs/tree/main/@rocketseat/gatsby-theme-docs#readme",
"repository": {
"type": "git",
"url": "https://github.com/jpedroschmitz/rocketdocs.git",
"directory": "@rocketseat/gatsby-theme-docs"
},
"bugs": {
"url": "https://github.com/jpedroschmitz/rocketdocs/issues"
},
"dependencies": {
"@emotion/react": "^11.11.0",
"@emotion/styled": "^11.11.0",
"@mdx-js/react": "^2.3.0",
"@rocketseat/gatsby-theme-docs-core": "^4.0.0",
"gatsby-plugin-catch-links": "^5.9.0",
"gatsby-plugin-emotion": "^8.9.0",
"gatsby-plugin-mdx": "^5.9.0",
"gatsby-plugin-react-helmet": "^6.9.0",
"mdx-utils": "^0.2.0",
"parse-numeric-range": "^1.3.0",
"polished": "^4.2.2",
"prism-react-renderer": "^1.2.1",
"prop-types": "^15.8.1",
"react-helmet": "^6.1.0",
"react-icons": "^4.8.0",
"react-live": "^4.0.1",
"react-use": "^17.4.0",
"url-join": "^4.0.1"
},
"peerDependencies": {
"gatsby": "^5.0.0",
"react": "^18.0.0",
"react-dom": "^18.0.0"
}
}
================================================
FILE: @rocketseat/gatsby-theme-docs/src/@rocketseat/gatsby-theme-docs-core/components/Docs.js
================================================
/* eslint-disable react/prop-types */
import React from 'react';
import Docs from '../../../components/Docs';
export default function Docspage({ data: { mdx }, pageContext, children }) {
return (
{children}
);
}
================================================
FILE: @rocketseat/gatsby-theme-docs/src/@rocketseat/gatsby-theme-docs-core/components/Homepage.js
================================================
/* eslint-disable react/prop-types */
import React from 'react';
import Home from '../../../components/Homepage';
export default function Homepage({ children }) {
return {children} ;
}
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/Code/LiveCodeScope.js
================================================
import { css, jsx } from '@emotion/react';
export default {
css,
jsx,
};
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/Code/index.js
================================================
import React, { useState } from 'react';
import PropTypes from 'prop-types';
import Highlight, { defaultProps } from 'prism-react-renderer';
import rangeParser from 'parse-numeric-range';
import theme from 'prism-react-renderer/themes/dracula';
import { LiveProvider, LiveEditor } from 'react-live';
import { copyToClipboard } from '../../util/copy-to-clipboard';
import scope from './LiveCodeScope';
import {
CopyCode,
LineNo,
Pre,
PreHeader,
LiveWrapper,
LivePreview,
LiveError,
StyledEditor,
} from './styles';
const calculateLinesToHighlight = (meta) => {
const RE = /{([\d,-]+)}/;
if (RE.test(meta)) {
const strlineNumbers = RE.exec(meta)[1];
const lineNumbers = rangeParser(strlineNumbers);
return (index) => lineNumbers.includes(index + 1);
}
return () => false;
};
export default function CodeHighlight({
codeString,
className,
live,
highlight,
title,
lineNumbers,
}) {
const [copied, setCopied] = useState(false);
const language = className && className.replace(/language-/, '');
const shouldHighlightLine = calculateLinesToHighlight(highlight);
const handleClick = () => {
setCopied(true);
copyToClipboard(codeString);
setTimeout(() => {
setCopied(false);
}, 4000);
};
if (live) {
return (
`/** @jsx mdx */${code}`}
scope={scope}
>
{copied ? 'Copied!' : 'Copy'}
);
}
return (
<>
{title && {title} }
{({
className: blockClassName,
style,
tokens,
getLineProps,
getTokenProps,
}) => (
{copied ? 'Copied!' : 'Copy'}
{tokens.map((line, index) => {
const lineProps = getLineProps({ line, key: index });
if (shouldHighlightLine(index)) {
lineProps.className = `${lineProps.className} highlight-line`;
}
return (
{lineNumbers && {index + 1} }
{line.map((token, key) => (
))}
);
})}
)}
);
}
CodeHighlight.propTypes = {
codeString: PropTypes.string.isRequired,
className: PropTypes.string.isRequired,
highlight: PropTypes.string,
live: PropTypes.oneOfType([PropTypes.string, PropTypes.bool]),
title: PropTypes.string,
lineNumbers: PropTypes.string,
};
CodeHighlight.defaultProps = {
live: false,
title: null,
lineNumbers: null,
highlight: null,
};
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/Code/styles.js
================================================
import styled from '@emotion/styled';
import { darken } from 'polished';
import {
LiveError as AuxLiveError,
LivePreview as AuxLivePreview,
} from 'react-live';
export const Pre = styled.pre`
text-align: left;
padding: ${({ hasLanguage }) => (hasLanguage ? `2rem` : `1rem`)} 1rem 1rem
1rem;
overflow: auto;
white-space: pre;
word-spacing: normal;
word-break: normal;
border-radius: ${({ hasTitle }) => (hasTitle ? '0 0 5px 5px' : '5px')};
-webkit-overflow-scrolling: touch;
overflow-wrap: break-word;
box-shadow: 1px 1px 20px rgba(20, 20, 20, 0.27);
code {
float: left;
min-width: 100%;
padding-right: 1rem;
}
.token-line {
line-height: 22px;
font-size: 14px;
min-width: 100%;
}
.highlight-line {
background-color: #44475a;
margin-left: -1rem;
margin-right: -2rem;
padding: 0 0.75rem;
border-left: 4px solid ${({ theme }) => theme.colors.primary};
}
`;
export const LiveWrapper = styled.div`
border-radius: 5px;
box-shadow: 1px 1px 20px rgba(20, 20, 20, 0.27);
overflow: hidden;
margin-bottom: 32px;
`;
export const StyledEditor = styled.div`
font-family: Hack, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
'Courier New', monospace;
font-variant: no-common-ligatures no-discretionary-ligatures
no-historical-ligatures no-contextual;
overflow: auto;
position: relative;
textarea,
pre {
font-size: 14px !important;
line-height: 22px !important;
padding: 1rem !important;
}
* > textarea:focus {
outline: none;
}
.token {
font-style: normal !important;
}
`;
export const LivePreview = styled(AuxLivePreview)`
position: relative;
padding: 0.5rem;
background: white;
color: black;
height: auto;
overflow: hidden;
`;
export const LiveError = styled(AuxLiveError)`
display: block;
color: rgb(248, 248, 242);
white-space: pre-wrap;
text-align: left;
font-size: 14px;
font-family: Hack, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
'Courier New', monospace;
font-variant: no-common-ligatures no-discretionary-ligatures
no-historical-ligatures no-contextual;
padding: 1rem;
background: rgb(255, 85, 85);
`;
export const PreHeader = styled.div`
background-color: ${darken('0.05', '#282a36')};
color: rgb(248, 248, 242, 0.75);
font-size: 12px;
line-height: 18px;
margin-top: 0.5rem;
padding: 0.8rem 1rem;
border-radius: 5px 5px 0 0;
`;
export const LineNo = styled.span`
display: inline-block;
width: 2rem;
user-select: none;
opacity: 0.3;
`;
export const CopyCode = styled.button`
position: absolute;
top: 0;
right: 0;
z-index: 1;
border-radius: ${({ hasTitle }) => (!hasTitle ? '0 5px 0 5px' : '0 0 0 5px')};
padding: 0.25rem 0.6rem;
border: none;
cursor: pointer;
background: #44475a;
color: rgb(248, 248, 242);
transition: all 200ms ease;
font-size: 12px;
:disabled {
cursor: not-allowed;
}
:not(:disabled) {
:hover,
:focus {
background: ${({ theme }) => theme.colors.primary};
}
}
`;
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/Docs/EditGithub.js
================================================
/* @jsx jsx */
import { useTheme, jsx, css } from '@emotion/react';
import PropTypes from 'prop-types';
import { MdEdit } from 'react-icons/md';
export default function EditGithub({ repositoryEditUrl, repositoryProvider }) {
const theme = useTheme();
if (repositoryEditUrl) {
return (
{prev && (
Prev
{prev.label}
)}
{next && (
Next
{next.label}
)}
);
}
Docs.propTypes = {
prev: PropTypes.shape({
label: PropTypes.string,
link: PropTypes.string,
}),
next: PropTypes.shape({
label: PropTypes.string,
link: PropTypes.string,
}),
};
Docs.defaultProps = {
prev: null,
next: null,
};
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/Docs/PostNav/styles.js
================================================
import styled from '@emotion/styled';
export const Container = styled.section`
display: flex;
justify-content: space-between;
align-items: center;
padding: 48px 0;
width: 100%;
@media (max-width: 780px) {
flex-direction: column;
}
`;
export const Post = styled.div`
transition: all 200ms;
${({ isLeft }) => !isLeft && 'margin-left: auto;'}
a {
display: flex;
text-decoration: none;
justify-content: center;
align-items: center;
width: 100%;
height: 100%;
svg {
width: 25px;
height: 25px;
color: ${({ theme }) => theme.colors.text};
${({ isLeft }) => (isLeft ? 'margin-right: 16px' : 'margin-left: 16px')};
}
p {
letter-spacing: 0.142em;
text-transform: uppercase;
font-size: 12px;
margin: 0;
color: ${({ theme }) => theme.colors.text};
}
h3 {
color: ${({ theme }) => theme.colors.text};
border: none;
margin: 0;
padding: 0;
font-size: 16px;
}
}
&:hover {
opacity: 0.8;
a svg {
opacity: 0.8;
}
}
@media (max-width: 780px) {
width: 100%;
${({ isLeft }) => isLeft && 'margin-bottom: 16px'};
a {
justify-content: ${({ isLeft }) => (isLeft ? 'flex-start' : 'flex-end')};
}
}
`;
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/Docs/TOC/index.js
================================================
import React, { useState, useEffect, useMemo } from 'react';
import PropTypes from 'prop-types';
import { useTheme } from '@emotion/react';
import useWindowScroll from 'react-use/lib/useWindowScroll';
import useWindowSize from 'react-use/lib/useWindowSize';
import slug from '../../../util/slug';
import { Wrapper, Container } from './styles';
export default function TableOfContents({ headings, disableTOC, contentRef }) {
const { y } = useWindowScroll();
const theme = useTheme();
const { width, height } = useWindowSize();
const [offsets, setOffsets] = useState([]);
const isMobile = width <= 1200;
useEffect(() => {
if (!isMobile || disableTOC) {
const allHeadings = contentRef.current?.querySelectorAll(`h2, h3`);
setOffsets(
allHeadings &&
Array.from(allHeadings)
.map((heading) => {
const anchor = heading.querySelector(`a`);
if (!anchor) return {};
return {
id: heading.id,
offset: heading.offsetTop + anchor.offsetTop,
};
})
.filter(Boolean),
);
}
}, [width, height, contentRef, isMobile, disableTOC]);
const activeHeading = useMemo(() => {
if (!isMobile || disableTOC) {
const windowOffset = height / 2;
const scrollTop = y + windowOffset;
if (offsets) {
for (let i = offsets.length - 1; i >= 0; i -= 1) {
const { id, offset } = offsets[i];
if (scrollTop >= offset) {
return id;
}
}
}
}
return null;
}, [offsets, height, y, isMobile, disableTOC]);
if (!disableTOC) {
return (
On this page
);
}
return
{children}
);
}
Docs.propTypes = {
mdx: PropTypes.shape({
body: PropTypes.string,
headings: PropTypes.array,
frontmatter: PropTypes.shape({
title: PropTypes.string,
description: PropTypes.string,
image: PropTypes.string,
disableTableOfContents: PropTypes.bool,
}),
fields: PropTypes.shape({
slug: PropTypes.string,
}),
}).isRequired,
pageContext: PropTypes.shape({
prev: PropTypes.shape({}),
next: PropTypes.shape({}),
repositoryEditUrl: PropTypes.string,
repositoryProvider: PropTypes.string,
}).isRequired,
children: PropTypes.node.isRequired,
};
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/Header.js
================================================
import React from 'react';
import PropTypes from 'prop-types';
import styled from '@emotion/styled';
import { GiHamburgerMenu } from 'react-icons/gi';
import { useStaticQuery, graphql } from 'gatsby';
const Container = styled.header`
display: flex;
justify-content: flex-start;
align-items: center;
height: 40px;
margin-bottom: 24px;
h2 {
margin: 0;
border: none;
padding: 0;
font-size: 18px;
@media (max-width: 359px) {
font-size: 14px;
}
}
button {
border: none;
background: none;
cursor: pointer;
margin-right: 16px;
display: flex;
justify-content: flex-start;
align-items: center;
}
@media (min-width: 780px) {
display: none;
}
`;
export default function Header({ handleMenuOpen }) {
const { site } = useStaticQuery(
graphql`
query {
site {
siteMetadata {
siteTitle
}
}
}
`,
);
const { siteTitle } = site.siteMetadata;
return (
{siteTitle}
);
}
Header.propTypes = {
handleMenuOpen: PropTypes.func.isRequired,
};
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/Homepage.js
================================================
import React from 'react';
import PropTypes from 'prop-types';
import Layout from './Layout';
import SEO from './SEO';
export default function Home({ children }) {
return (
);
}
Home.propTypes = {
children: PropTypes.node.isRequired,
};
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/Layout/index.js
================================================
/* @jsx jsx */
import { useState, useRef, Fragment } from 'react';
import { jsx, css } from '@emotion/react';
import PropTypes from 'prop-types';
import TableOfContents from '../Docs/TOC';
import Sidebar from '../Sidebar';
import Header from '../Header';
import Overlay from '../Overlay';
import { Container, Main, Children } from './styles';
export default function Layout({
children,
disableTableOfContents,
title,
headings,
}) {
const contentRef = useRef(null);
const [isMenuOpen, setMenuOpen] = useState(false);
const disableTOC =
disableTableOfContents === true || !headings || headings.length === 0;
const handleMenuOpen = () => {
setMenuOpen(!isMenuOpen);
};
return (
{title}
)}
{title && (
{title}
)}
{children}
);
}
Layout.propTypes = {
children: PropTypes.oneOfType([
PropTypes.arrayOf(PropTypes.node),
PropTypes.node,
]).isRequired,
disableTableOfContents: PropTypes.bool,
title: PropTypes.string,
headings: PropTypes.array,
};
Layout.defaultProps = {
disableTableOfContents: false,
title: '',
headings: null,
};
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/Layout/styles.js
================================================
import styled from '@emotion/styled';
export const Container = styled.div`
width: 100%;
max-width: 1400px;
margin: 0 auto;
padding: 0 24px;
display: grid;
grid-template-columns: 280px calc(100% - 320px);
grid-auto-flow: row;
grid-gap: 40px;
@media (max-width: 780px) {
padding: 24px;
grid-template-columns: 100%;
}
`;
export const Main = styled.main`
height: 100%;
padding-top: 36px;
width: 100%;
display: flex;
justify-content: flex-start;
position: relative;
@media (max-width: 1200px) {
flex-direction: column;
}
@media (max-width: 780px) {
padding-top: 0;
}
`;
export const Children = styled.div`
width: 100%;
max-width: calc(75% - 64px);
padding-right: 64px;
@media (max-width: 1200px) {
max-width: 100%;
padding-right: 0;
order: 3;
}
h1,
h2,
h3,
h4,
h5,
h6 {
overflow-wrap: break-word;
}
`;
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/Logo.js
================================================
import React from 'react';
export default function Logo(props) {
return (
);
}
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/Overlay.js
================================================
/* @jsx jsx */
import { css, jsx } from '@emotion/react';
import PropTypes from 'prop-types';
export default function Overlay({ isMenuOpen, ...rest }) {
return (
);
}
Overlay.propTypes = {
isMenuOpen: PropTypes.bool,
};
Overlay.defaultProps = {
isMenuOpen: false,
};
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/SEO.js
================================================
import React from 'react';
import PropTypes from 'prop-types';
import Helmet from 'react-helmet';
import urljoin from 'url-join';
import { useStaticQuery, graphql } from 'gatsby';
export default function SEO({ description, title, slug, image, children }) {
const { site } = useStaticQuery(
graphql`
query {
site {
siteMetadata {
defaultTitle
siteTitleShort
siteTitle
siteImage
siteDescription
siteLanguage
siteUrl
siteAuthor
}
}
}
`,
);
const {
siteTitle,
siteTitleShort,
siteUrl,
defaultTitle,
siteImage,
siteDescription,
siteLanguage,
siteAuthor,
siteIcon,
} = site.siteMetadata;
const metaTitle = title ? `${title} | ${siteTitle}` : defaultTitle;
const metaUrl = urljoin(siteUrl, slug);
const metaImage = urljoin(siteUrl, image || siteImage);
const metaDescription = description || siteDescription;
const schemaOrgJSONLD = [
{
'@context': 'http://schema.org',
'@type': 'WebSite',
url: metaUrl,
name: title,
alternateName: siteTitleShort,
},
];
return (
{siteIcon && }
{children}
);
}
SEO.propTypes = {
title: PropTypes.string,
description: PropTypes.string,
slug: PropTypes.string,
image: PropTypes.string,
children: PropTypes.oneOfType([
PropTypes.arrayOf(PropTypes.element),
PropTypes.node,
]),
};
SEO.defaultProps = {
title: '',
description: '',
slug: '',
image: '',
children: '',
};
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/Sidebar/ExternalLink/index.js
================================================
import React from 'react';
import PropTypes from 'prop-types';
import { FiExternalLink } from 'react-icons/fi';
export default function ExternalLink({ link, label }) {
return (
{label}
{text}
{children}
);
}
export default function Sidebar({ isMenuOpen }) {
const {
site: {
siteMetadata: { basePath },
},
} = useStaticQuery(graphql`
{
site {
siteMetadata {
basePath
}
}
}
`);
const data = useSidebar();
function renderLink(link, label) {
return isExternalUrl(link) ? (
);
}
ListWithSubItems.propTypes = {
children: PropTypes.oneOfType([
PropTypes.arrayOf(PropTypes.element),
PropTypes.node,
]).isRequired,
text: PropTypes.string.isRequired,
};
Sidebar.propTypes = {
isMenuOpen: PropTypes.bool.isRequired,
};
================================================
FILE: @rocketseat/gatsby-theme-docs/src/components/Sidebar/styles.js
================================================
import styled from '@emotion/styled';
export const Container = styled.aside`
width: 100%;
overflow-y: auto;
display: flex;
justify-content: space-between;
align-items: center;
flex-direction: column;
position: sticky;
top: 0;
padding-top: 36px;
transition: transform 0.5s;
height: calc(100vh - 1px);
nav {
width: 100%;
padding-top: 24px;
align-self: flex-start;
flex: 1;
}
@media (max-width: 780px) {
max-width: 75%;
min-width: auto;
z-index: 1001;
position: fixed;
top: 0;
bottom: 0;
left: 0;
padding-top: 32px;
background: ${({ theme }) => theme.colors.background};
transform: translate3d(
${({ isMenuOpen }) => (isMenuOpen ? '0' : '-100%')},
0,
0
);
}
`;
export const LogoContainer = styled.div`
width: 100%;
a {
width: 100%;
padding-left: 30px;
display: flex;
justify-content: flex-start;
align-items: center;
}
`;
export const List = styled.ul`
list-style: none;
width: 100%;
padding-left: 0;
display: flex;
justify-content: flex-start;
align-items: center;
flex-direction: column;
`;
export const Heading = styled.li`
padding-left: 30px;
width: 100%;
text-transform: uppercase;
font-size: 14px;
font-weight: bold;
margin-top: 20px;
color: ${({ theme }) => theme.colors.title};
letter-spacing: 0.142em;
`;
export const Item = styled.li`
font-size: 15px;
width: 100%;
transition: all 200ms ease-in-out;
padding: 0 20px;
cursor: pointer;
a,
span {
display: block;
font-size: 15px;
color: ${({ theme }) => theme.colors.text};
background-color: ${({ theme }) => theme.colors.background};
padding: 4px 10px;
margin: 4px 0;
border-radius: 4px;
font-weight: normal;
text-decoration: none;
width: 100%;
height: 100%;
display: flex;
justify-content: flex-start;
align-items: center;
cursor: pointer;
margin: 0 auto;
transition: all 0.2s ease;
svg {
width: 20px;
height: 20px;
margin-right: 10px;
}
&:not(.active-link):hover {
color: ${({ theme }) => theme.colors.primary};
}
&.active-link {
color: ${({ theme }) => theme.colors.primary};
background-color: ${({ theme }) => theme.colors.shape};
}
@media (max-width: 780px) {
&.active-link {
background: ${({ theme }) => theme.colors.shape};
}
}
}
`;
export const SubItem = styled(List)`
margin: 5px 0 0 0;
`;
================================================
FILE: @rocketseat/gatsby-theme-docs/src/styles/global.js
================================================
import React from 'react';
import { useTheme, Global, css } from '@emotion/react';
export default function GlobalStyle() {
const theme = useTheme();
return (
@rocketseat/gatsby-theme-docs-core
Core theme for @rocketseat/gatsby-theme-docs with no additional theming or style opinions. Includes all of the data structures you need to get up and build a documentation website.
Features •
Getting started •
Usage •
Contributing •
License
## 🚀 Features
- MDX for docs;
- Sidebar customization with Yaml;
## ⚡️ Getting started
Using Yarn:
```sh
yarn add @rocketseat/gatsby-theme-docs-core
```
Using NPM:
```sh
npm i @rocketseat/gatsby-theme-docs-core
```
## 🔥 Usage
### Theme options
| Key | Default | Required | Description |
| ------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| basePath | / | No | Root url for all docs |
| configPath | config | No | Location of config files |
| docsPath | docs | No | The site description for SEO and social (FB, Twitter) tags |
| githubUrl | - | - | Deprecated in favor of `repositoryUrl` |
| repositoryUrl | - | No | The URL of your repository (supports GitHub, GitLab and Bitbucket). Example: `https://github/jpedroschmitz/rocketdocs` |
| baseDir | - | No | If your Gatsby site does not live in the root of your project directory/git repo, pass the subdirectory name here (`docs`, for example) |
| withMdx | true | No | If necessary, you can add your own MDX options to the theme. To do so, make sure you turn this option to false and include `gatsby-plugin-mdx` on your `gatsby-config` |
| branch | main | No | Default branch of the repository |
> Note: When adding a BitBucket link on the `repositoryUrl` option, don't add the `src/` to it.
> Example of correct link: `https://bitbucket.org/jpedroschmitz/rocketdocs`
### Example usage
```js
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: `@rocketseat/gatsby-theme-docs-core`,
options: {
basePath: `documentation`,
configPath: `config`,
docsPath: `docs`,
githubUrl: `https://github.com/jpedroschmitz/rocketdocs`,
baseDir: `www`,
},
},
],
};
```
### Navigation
The sidebar is highly customizable, you can create a file under the config folder named `sidebar.yml`. If you add a `basePath` in the theme options, you don't need to add it before the links, the `useSidebar` hook will append it.
Here is an example:
```yml
# Simple item
- label: 'Home'
link: '/'
# With list of subitems
- label: 'With dropdown'
items:
- label: 'My Example'
link: '/my-example'
```
### `useSidebar`
To get all the sidebar items, you can use the `useSidebar` hook. Example:
```js
import React from 'react';
import { useSidebar } from '@rocketseat/gatsby-theme-docs-core';
export default function Sidebar() {
const data = useSidebar();
console.log(data);
/*
[
{
"node": {
"label": "Home",
"link": "/",
"items": null,
"id": "a2913be3-af3c-5fc9-967e-a058e86b20a9"
}
},
{
"node": {
"label": "With dropdown",
"link": null,
"items": [{ "label": "My Example", "link": "/my-example" }],
"id": "c7d9606c-4bda-5097-a0df-53108e9f4efd"
}
}
]
*/
}
```
### Docs Fields
Inside your docs folder, you can create MDX files. The filename will be the page path.
Add a title to the frontmatter of the MDX file and place the content below it. For example:
```mdx
---
title: 'My Example'
description: 'A simple description for this page'
image: 'banner.png'
disableTableOfContents: false
---
Your amazing page
```
Every file must have a custom title. Description and image are not required.
### Shadowing
Check the [Shadowing in Gatsby Themes](https://www.gatsbyjs.com/docs/themes/shadowing/) docs to understand how to customize this theme!
In general, you will need to create two files (`Docs.js` and `Homepage.js`) into `src/@rocketseat/gatsby-theme-docs-core/components/templates` to shadow/override it.
## ✨ Contributing
Thanks for being interested in contributing! We’re so glad you want to help! Please take a little bit of your time and look at our [contributing guidelines](https://github.com/jpedroschmitz/rocketdocs/blob/main/.github/CONTRIBUTING.md) and our
[code of conduct](https://github.com/jpedroschmitz/rocketdocs/blob/main/.github/CODE_OF_CONDUCT.md)! All type of contributions are welcome, such as bug fixes, issues or feature requests.
## 📝 License
Licensed under the [MIT License](https://github.com/jpedroschmitz/rocketdocs/blob/main/%40rocketseat/gatsby-theme-docs-core/LICENSE).
---
Made with 💜 by João Pedro
================================================
FILE: @rocketseat/gatsby-theme-docs-core/gatsby-config.js
================================================
const withDefault = require(`./util/with-default`);
const path = require(`path`);
const gfmPlugin = require(`remark-gfm`);
const { rehypeMetaAsAttributes } = require(`./rehype-meta-as-attributes`);
const camelCase = require('lodash.camelcase');
const upperFirst = (text) => text.charAt(0).toUpperCase() + text.slice(1);
module.exports = (options) => {
const {
basePath,
configPath,
docsPath,
yamlFilesPath,
withMdx,
gatsbyRemarkPlugins,
} = withDefault(options);
return {
siteMetadata: {
basePath,
},
plugins: [
`gatsby-transformer-sharp`,
`gatsby-plugin-sharp`,
{
resolve: `gatsby-source-filesystem`,
options: {
name: `docs`,
path: docsPath,
},
},
{
resolve: `gatsby-source-filesystem`,
options: {
name: `config`,
path: configPath,
},
},
{
resolve: `gatsby-source-filesystem`,
options: {
name: `yamlFiles`,
path: yamlFilesPath,
},
},
{
resolve: `gatsby-transformer-yaml`,
options: {
typeName: ({ node, isArray }) => {
if (node.sourceInstanceName === `config`) {
return `SidebarItems`;
}
// Fallback to the existing algorithm from gatsby-transformer-yaml plugin.
// https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-transformer-yaml/src/gatsby-node.js#L22-L28
if (node.internal.type !== `File`) {
return upperFirst(camelCase(`${node.internal.type} Yaml`));
}
// Parsing algorithm: Array of Objects, where each file represents a collection.
if (isArray) {
return upperFirst(camelCase(`${node.name} Yaml`));
}
// Parsing algorithm: Single Object, where each subfolder represents a collection; each file represents one "record".
return upperFirst(camelCase(`${path.basename(node.dir)} Yaml`));
},
},
},
withMdx && {
resolve: `gatsby-plugin-mdx`,
options: {
extensions: [`.mdx`, `.md`],
mdxOptions: {
remarkPlugins: [gfmPlugin],
rehypePlugins: [rehypeMetaAsAttributes],
},
gatsbyRemarkPlugins: [
`gatsby-remark-autolink-headers`,
`gatsby-remark-embedder`,
{
resolve: `gatsby-remark-images`,
options: {
maxWidth: 960,
withWebp: true,
linkImagesToOriginal: false,
},
},
`gatsby-remark-responsive-iframe`,
`gatsby-remark-copy-linked-files`,
...gatsbyRemarkPlugins,
],
},
},
].filter(Boolean),
};
};
================================================
FILE: @rocketseat/gatsby-theme-docs-core/gatsby-node.js
================================================
const path = require(`path`);
const { createFilePath } = require(`gatsby-source-filesystem`);
const fs = require(`fs`);
const urljoin = require(`url-join`);
const { compileMDXWithCustomOptions } = require(`gatsby-plugin-mdx`);
const { normalizeBasePath, resolveLink } = require(`./util/url`);
const withDefault = require(`./util/with-default`);
const { remarkHeadingsPlugin } = require(`./remark-headings-plugin`);
function generateRepositoryEditLink(themeOptions, relativePath) {
const { baseDir, docsPath, repositoryUrl, githubUrl, branch } =
withDefault(themeOptions);
const repoUrl = !repositoryUrl && githubUrl ? githubUrl : repositoryUrl;
const pathToFile = path.join(branch, baseDir, docsPath);
if (repoUrl.includes('github')) {
return {
editUrl: urljoin(repoUrl, `tree`, pathToFile, relativePath),
provider: `GitHub`,
};
}
if (repoUrl.includes('gitlab')) {
return {
editUrl: urljoin(repoUrl, '-', 'blob', pathToFile, relativePath),
provider: `GitLab`,
};
}
if (repoUrl.includes('bitbucket')) {
return {
editUrl: urljoin(repoUrl, 'src', pathToFile, relativePath),
provider: `BitBucket`,
};
}
return {
editUrl: null,
provider: null,
};
}
exports.createPages = (
{ graphql, actions: { createPage }, reporter },
themeOptions,
) => {
reporter.success(`onCreateDocs`);
const { basePath, githubUrl, repositoryUrl } = withDefault(themeOptions);
const docsTemplate = require.resolve(`./src/templates/docs-query.js`);
const homeTemplate = require.resolve(`./src/templates/homepage-query.js`);
return graphql(
`
{
files: allFile(
filter: {
extension: { in: ["md", "mdx"] }
sourceInstanceName: { eq: "docs" }
}
) {
edges {
node {
id
relativePath
childMdx {
fields {
slug
}
internal {
contentFilePath
}
}
}
}
}
sidebar: allSidebarItems {
edges {
node {
label
link
items {
label
link
}
id
}
}
}
homepage: allMdx(filter: { fields: { slug: { eq: "/" } } }) {
nodes {
internal {
contentFilePath
}
}
}
}
`,
).then((result) => {
if (result.errors) {
reporter.panic(
`docs: there was an error loading the docs folder!`,
result.errors,
);
return;
}
if (!repositoryUrl && githubUrl) {
reporter.warn(
`@rocketseat/gatsby-theme-docs: The option \`githubUrl\` was deprecated in favor of \`repositoryUrl\`. \nTo remove this warning, replace \`githubUrl\` with \`repositoryUrl\`.`,
);
}
const homepage = result.data.homepage.nodes[0];
createPage({
path: basePath,
component: `${homeTemplate}?__contentFilePath=${homepage.internal.contentFilePath}`,
context: {},
});
// Generate prev/next items based on sidebar.yml file
const sidebar = result.data.sidebar.edges;
const listOfItems = [];
sidebar.forEach(({ node: { label, link, items } }) => {
if (Array.isArray(items)) {
items.forEach((item) => {
listOfItems.push({
label: item.label,
link: resolveLink(item.link, basePath),
});
});
} else {
listOfItems.push({
label,
link: resolveLink(link, basePath),
});
}
});
// Generate docs pages
const docs = result.data.files.edges;
docs.forEach((doc) => {
const {
childMdx: {
fields: { slug },
internal: { contentFilePath },
},
relativePath,
} = doc.node;
// Get the file edit link based on the repository url
const repositoryEditUrl = generateRepositoryEditLink(
themeOptions,
relativePath,
);
const pageLink = slug.slice(0, slug.length - 1);
const currentPageIndex = listOfItems.findIndex(
(page) => page.link === pageLink,
);
const prev = listOfItems[currentPageIndex - 1];
const next = listOfItems[currentPageIndex + 1];
createPage({
path: slug,
component: `${docsTemplate}?__contentFilePath=${contentFilePath}`,
context: {
slug,
prev,
next,
repositoryEditUrl: repositoryEditUrl.editUrl || '',
repositoryProvider: repositoryEditUrl.provider || '',
},
});
});
reporter.success(`docs pages created`);
});
};
exports.createSchemaCustomization = async ({
getNode,
getNodesByType,
pathPrefix,
reporter,
cache,
actions,
schema,
store,
}) => {
const { createTypes } = actions;
createTypes(`
type MdxFrontmatter {
title: String!
description: String
image: String
disableTableOfContents: Boolean
}
`);
createTypes(`
type SidebarItems implements Node {
label: String!
link: String
items: [SidebarItemsItems]
}
type SidebarItemsItems {
label: String
link: String
}
`);
const headingsResolver = schema.buildObjectType({
name: `Mdx`,
fields: {
headings: {
type: `[MdxHeading]`,
async resolve(mdxNode) {
const fileNode = getNode(mdxNode.parent);
if (!fileNode) {
return null;
}
const result = await compileMDXWithCustomOptions(
{
source: mdxNode.body,
absolutePath: fileNode.absolutePath,
},
{
pluginOptions: {},
customOptions: {
mdxOptions: {
remarkPlugins: [remarkHeadingsPlugin],
},
},
getNode,
getNodesByType,
pathPrefix,
reporter,
cache,
store,
},
);
if (!result) {
return null;
}
return result.metadata.headings;
},
},
},
});
createTypes([
`
type MdxHeading {
value: String
depth: Int
}
`,
headingsResolver,
]);
};
exports.onPreBootstrap = ({ store, reporter }, themeOptions) => {
const { configPath, docsPath, yamlFilesPath } = withDefault(themeOptions);
const { program } = store.getState();
const dirs = [
path.join(program.directory, configPath),
path.join(program.directory, docsPath),
path.join(program.directory, yamlFilesPath),
];
dirs.forEach((dir) => {
if (!fs.existsSync(dir)) {
reporter.success(`docs: initialized the ${dir} directory`);
fs.mkdirSync(dir);
}
});
};
exports.onCreateNode = (
{ node, actions: { createNodeField }, getNode },
themeOptions,
) => {
if (node.internal.type !== `Mdx`) {
return;
}
const { basePath } = withDefault(themeOptions);
let value = createFilePath({ node, getNode });
if (value === 'index') value = '';
createNodeField({
name: `slug`,
node,
value: normalizeBasePath(basePath, value),
});
createNodeField({
name: `id`,
node,
value: node.id,
});
};
================================================
FILE: @rocketseat/gatsby-theme-docs-core/index.js
================================================
export { useSidebar } from './src/hooks/useSidebar';
================================================
FILE: @rocketseat/gatsby-theme-docs-core/package.json
================================================
{
"name": "@rocketseat/gatsby-theme-docs-core",
"version": "4.0.0",
"main": "index.js",
"description": "Core theme for @rocketseat/gatsby-theme-docs with no additional theming or style opinions. Includes all of the data structures you need to get up and build a documentation website.",
"author": "João Pedro Schmitz (@jpedroschmitz)",
"license": "MIT",
"publishConfig": {
"access": "public"
},
"keywords": [
"documentation",
"open source",
"gatsby",
"gatsby-plugin",
"gatsby-theme",
"react",
"docs",
"mdx"
],
"homepage": "https://github.com/jpedroschmitz/rocketdocs/tree/main/@rocketseat/gatsby-theme-docs-core#readme",
"repository": {
"type": "git",
"url": "https://github.com/jpedroschmitz/rocketdocs.git",
"directory": "@rocketseat/gatsby-theme-docs-core"
},
"bugs": {
"url": "https://github.com/jpedroschmitz/rocketdocs/issues"
},
"dependencies": {
"@mdx-js/mdx": "^1.6.22",
"gatsby-plugin-mdx": "^5.9.0",
"gatsby-plugin-sharp": "^5.9.0",
"gatsby-remark-autolink-headers": "^6.9.0",
"gatsby-remark-copy-linked-files": "^6.9.0",
"gatsby-remark-embedder": "^6.0.1",
"gatsby-remark-images": "^7.9.0",
"gatsby-remark-responsive-iframe": "^6.9.0",
"gatsby-source-filesystem": "^5.9.0",
"gatsby-transformer-sharp": "^5.9.0",
"gatsby-transformer-yaml": "^5.9.0",
"lodash.camelcase": "^4.3.0",
"mdast-util-to-string": "^2",
"remark-gfm": "^1",
"unist-util-visit": "^2",
"url-join": "^4.0.1"
},
"peerDependencies": {
"@mdx-js/react": "^2.3.0",
"gatsby": "^5.0.0",
"react": "^18.0.0",
"react-dom": "^18.0.0"
}
}
================================================
FILE: @rocketseat/gatsby-theme-docs-core/rehype-meta-as-attributes.js
================================================
const visit = require(`unist-util-visit`);
exports.rehypeMetaAsAttributes = function rehypeMetaAsAttributes() {
return (tree) => {
// A regex that looks for a simplified attribute name, optionally followed
// by a double, single, or unquoted attribute value
const re = /\b([-\w]+)(?:=(?:"([^"]*)"|'([^']*)'|([^"'\s]+)))?/g;
// …
visit(tree, 'element', (node) => {
let match;
if (node.tagName === 'code' && node.data && node.data.meta) {
re.lastIndex = 0; // Reset regex.
// eslint-disable-next-line no-cond-assign
while ((match = re.exec(node.data.meta))) {
node.properties[match[1]] = match[2] || match[3] || match[4] || '';
}
}
});
// …
};
};
================================================
FILE: @rocketseat/gatsby-theme-docs-core/remark-headings-plugin.js
================================================
const visit = require(`unist-util-visit`);
const toString = require(`mdast-util-to-string`);
exports.remarkHeadingsPlugin = function remarkHeadingsPlugin() {
return async function transformer(tree, file) {
const headings = [];
visit(tree, `heading`, (heading) => {
headings.push({
value: toString(heading),
depth: heading.depth,
});
});
const mdxFile = file;
if (!mdxFile.data.meta) {
mdxFile.data.meta = {};
}
mdxFile.data.meta.headings = headings;
};
};
================================================
FILE: @rocketseat/gatsby-theme-docs-core/src/components/Docs.js
================================================
/* eslint-disable react/prop-types */
import React from 'react';
export default function Docspage({ data }) {
return {JSON.stringify(data, null, 2)};
}
================================================
FILE: @rocketseat/gatsby-theme-docs-core/src/components/Homepage.js
================================================
/* eslint-disable react/prop-types */
import React from 'react';
export default function Homepage({ data }) {
return {JSON.stringify(data, null, 2)};
}
================================================
FILE: @rocketseat/gatsby-theme-docs-core/src/hooks/useSidebar.js
================================================
import { graphql, useStaticQuery } from 'gatsby';
import { resolveLink } from '../../util/url';
export function useSidebar() {
const data = useStaticQuery(graphql`
{
allSidebarItems {
edges {
node {
label
link
items {
label
link
}
id
}
}
}
site {
siteMetadata {
basePath
}
}
}
`);
const { basePath } = data.site.siteMetadata;
const {
allSidebarItems: { edges },
} = data;
if (basePath) {
const normalizedSidebar = edges.map(
({ node: { label, link, items, id } }) => {
if (Array.isArray(items)) {
items = items.map((item) => ({
label: item.label,
link: resolveLink(item.link, basePath),
}));
}
return {
node: {
id,
label,
items,
link: resolveLink(link, basePath),
},
};
},
);
return normalizedSidebar;
}
return edges;
}
================================================
FILE: @rocketseat/gatsby-theme-docs-core/src/templates/docs-query.js
================================================
import { graphql } from 'gatsby';
import DocsComponent from '../components/Docs';
export default DocsComponent;
export const query = graphql`
query ($slug: String!) {
mdx(fields: { slug: { eq: $slug } }) {
id
excerpt(pruneLength: 160)
fields {
slug
}
frontmatter {
title
description
image
disableTableOfContents
}
headings {
depth
value
}
}
}
`;
================================================
FILE: @rocketseat/gatsby-theme-docs-core/src/templates/homepage-query.js
================================================
import HomepageComponent from '../components/Homepage';
export default HomepageComponent;
================================================
FILE: @rocketseat/gatsby-theme-docs-core/util/url.js
================================================
function normalizeBasePath(basePath, link) {
return `/${basePath}/${link}`.replace(/\/\/+/g, `/`);
}
function isExternalUrl(url) {
return /^((https?:)?\/\/)/i.test(url);
}
function resolveLink(link, basePath) {
return isExternalUrl(link) ? link : normalizeBasePath(basePath, link);
}
module.exports = { resolveLink, normalizeBasePath, isExternalUrl };
================================================
FILE: @rocketseat/gatsby-theme-docs-core/util/with-default.js
================================================
module.exports = (themeOptions) => {
const basePath = themeOptions.basePath || `/`;
const homePath = themeOptions.homePath || ``;
const configPath = themeOptions.configPath || `config`;
const docsPath = themeOptions.docsPath || `docs`;
const yamlFilesPath = themeOptions.yamlFilesPath || `yamlFiles`;
const branch = themeOptions.branch || `main`;
const baseDir = themeOptions.baseDir || ``;
const withMdx =
themeOptions.withMdx === undefined ? true : themeOptions.withMdx;
const gatsbyRemarkPlugins = themeOptions.gatsbyRemarkPlugins || [];
const { githubUrl, repositoryUrl = '' } = themeOptions;
return {
basePath,
homePath,
configPath,
docsPath,
yamlFilesPath,
baseDir,
githubUrl,
repositoryUrl,
withMdx,
branch,
gatsbyRemarkPlugins,
};
};
================================================
FILE: LICENSE.md
================================================
MIT License
Copyright (c) 2021 João Pedro Schmitz
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: README.md
================================================
Rocket Docs
Easy to use Gatsby Theme to create documentation websites ⚡️🔥
Themes •
Contributing •
Need help? •
License
## Themes
🚀 [`gatsby-theme-docs-core`](./@rocketseat/gatsby-theme-docs-core): The core theme for docs websites that includes all the data structures you need.
🚀 [`gatsby-theme-docs`](./@rocketseat/gatsby-theme-docs): Out of the box Gatsby Theme for creating documentation websites easily and quickly.
## Contributing
Thanks for being interested in contributing! We’re so glad you want to help! Please take a little bit of your time and look at our [contributing guidelines](.github/CONTRIBUTING.md) and our
[code of conduct](.github/CODE_OF_CONDUCT.md)! All type of contributions are welcome, such as bug fixes, issues or feature requests. Also, don't forget to check the roadmap.
## Need help?
If you need help, feel free to open an issue with a description of the problem
you're facing or, if you prefer, you can chat with us on our
[forum](https://github.com/jpedroschmitz/rocketdocs/discussions).
## Sponsors
## Thanks
The following Open Source projects heavily inspire this project! Thanks, Apollo and LekoArts!
- [LekoArts Gatsby themes](https://github.com/LekoArts/gatsby-themes)
- [Apollo Gatsby themes](https://github.com/apollographql/gatsby-theme-apollo)
## License
MIT © [João Pedro](https://github.com/jpedroschmitz)
================================================
FILE: examples/gatsby-theme-docs/.gitignore
================================================
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Runtime data
pids
*.pid
*.seed
*.pid.lock
# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov
# Coverage directory used by tools like istanbul
coverage
# nyc test coverage
.nyc_output
# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
.grunt
# Bower dependency directory (https://bower.io/)
bower_components
# node-waf configuration
.lock-wscript
# Compiled binary addons (http://nodejs.org/api/addons.html)
build/Release
# Dependency directories
node_modules/
jspm_packages/
# Typescript v1 declaration files
typings/
# Optional npm cache directory
.npm
# Optional eslint cache
.eslintcache
# Optional REPL history
.node_repl_history
# Output of 'npm pack'
*.tgz
# dotenv environment variable files
.env*
# gatsby files
.cache/
public
# Mac files
.DS_Store
# Yarn
yarn-error.log
.pnp/
.pnp.js
# Yarn Integrity file
.yarn-integrity
================================================
FILE: examples/gatsby-theme-docs/LICENSE
================================================
MIT License
Copyright (c) 2021 João Pedro
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: examples/gatsby-theme-docs/README.md
================================================
Gatsby Starter: Rocket Docs
Out of the box Gatsby Starter for creating documentation websites easily and quickly. With support for MDX, code highlight, Analytics, SEO and more 🔥 Using the theme: @rocketseat/gatsby-theme-docs
## 🚀 Features
- 📝 MDX for docs;
- 🛣 Yaml-based sidebar navigation;
- 📱 Responsive and mobile friendly;
- 🖥 Code highlighting with [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) and [react-live](https://github.com/FormidableLabs/react-live) support;
- 🥇 SEO (Sitemap, schema.org data, Open Graph and Twitter tags).
- 📈 Google Analytics support;
- 📄 Custom docs schema;
- 🖱 Table of Contents;
- ⚡️ Offline Support & WebApp Manifest;
- and much more 🔥
## ⚡️ Getting started
1. Create the website.
```sh
npx gatsby new rocketdocs https://github.com/jpedroschmitz/gatsby-starter-rocketdocs
```
2. Start developing.
```sh
cd rocketdocs
gatsby develop
```
3. Are you ready for launch?
Your site is now running at `http://localhost:8000`
## 📄 Docs
Looking for docs? Check our live demo and documentation [website](https://rocketdocs.netlify.app).
---
Made with 💜 by João Pedro
================================================
FILE: examples/gatsby-theme-docs/gatsby-config.js
================================================
module.exports = {
siteMetadata: {
siteTitle: `Rocket Docs`,
defaultTitle: `Rocket Docs`,
siteTitleShort: `Rocket Docs`,
siteDescription: `Out of the box Gatsby Theme for creating documentation websites easily and quickly`,
siteUrl: `https://rocketdocs.netlify.app`,
siteAuthor: `@jpedroschmitz`,
siteImage: `/banner.png`,
siteLanguage: `en`,
themeColor: `#8257E6`,
basePath: `/`,
},
plugins: [
{
resolve: `@rocketseat/gatsby-theme-docs`,
options: {
configPath: `src/config`,
docsPath: `src/docs`,
homePath: `src/home`,
yamlFilesPath: `src/yamlFiles`,
repositoryUrl: `https://github.com/jpedroschmitz/rocketdocs`,
baseDir: `examples/gatsby-theme-docs`,
gatsbyRemarkPlugins: [],
},
},
{
resolve: `gatsby-plugin-manifest`,
options: {
name: `Rocket Docs`,
short_name: `Rocket Docs`,
start_url: `/`,
background_color: `#ffffff`,
display: `standalone`,
icon: `static/favicon.png`,
},
},
`gatsby-plugin-sitemap`,
// {
// resolve: `gatsby-plugin-google-analytics`,
// options: {
// trackingId: `YOUR_ANALYTICS_ID`,
// },
// },
`gatsby-plugin-remove-trailing-slashes`,
{
resolve: `gatsby-plugin-canonical-urls`,
options: {
siteUrl: `https://rocketdocs.netlify.app`,
},
},
`gatsby-plugin-offline`,
],
};
================================================
FILE: examples/gatsby-theme-docs/package.json
================================================
{
"name": "gatsby-starter-rocketdocs",
"private": true,
"version": "1.0.0",
"description": "Out of the box Gatsby Starter for creating documentation websites easily and quickly. With support for MDX, code highlight, Analytics, SEO and more",
"author": "João Pedro Schmitz (@jpedroschmitz)",
"license": "MIT",
"starter-name": "gatsby-starter-rocketdocs",
"dependencies": {
"@rocketseat/gatsby-theme-docs": "^4.0.1",
"gatsby": "^5.9.0",
"gatsby-plugin-canonical-urls": "^5.9.0",
"gatsby-plugin-google-analytics": "^5.9.0",
"gatsby-plugin-manifest": "^5.9.0",
"gatsby-plugin-offline": "^6.9.0",
"gatsby-plugin-remove-trailing-slashes": "^4.2.0",
"gatsby-plugin-sitemap": "^6.9.0",
"prop-types": "^15.8.1",
"react": "^18.2.0",
"react-dom": "^18.2.0"
},
"devDependencies": {},
"keywords": [
"gatsby",
"gatsby-starter"
],
"scripts": {
"build": "gatsby build",
"start": "gatsby develop",
"serve": "gatsby serve",
"clean": "gatsby clean"
}
}
================================================
FILE: examples/gatsby-theme-docs/src/config/sidebar.yml
================================================
# Sidebar navigation
- label: 'Introduction'
link: '/'
- label: 'Getting started'
link: '/getting-started'
- label: Usage
items:
- label: 'Creating docs'
link: '/usage/creating-docs'
- label: 'Navigation'
link: '/usage/navigation'
- label: 'Customizing'
link: '/usage/customizing'
- label: 'Using YAML files'
link: '/usage/using-yaml-files'
- label: 'Remark Plugins'
link: '/usage/remark-plugins'
- label: More
items:
- label: FAQ
link: /faq
- label: 'Github'
link: https://github.com/jpedroschmitz/rocketdocs
================================================
FILE: examples/gatsby-theme-docs/src/docs/faq.mdx
================================================
---
title: Frequently Asked Questions
description: Frequently asked questions about the theme.
disableTableOfContents: true
---
## Will be included search or dark mode?
This theme is a great and complete option to build simple documentation websites.
We don't plan anymore to include search, dark mode or i18n to the project.
Remember that if necessary, you can change colors and include a default
dark theme. To do so, check this [doc](/usage/shadowing#changing-theme-colors).
## How can I deploy my website?
To deploy this project, we recommend you take a look at this extensive documentation
hosted on [Gatsby website](https://www.gatsbyjs.com/docs/deploying-and-hosting/). It
includes deploy tutorials for many services, like [Vercel](https://vercel.com/),
[Netlify](https://www.netlify.com/), [GitHub Pages](https://pages.github.com/) and others.
## What are good examples of the theme usage?
- [Botmation](https://botmation.dev)
- [Capmonster.cloud for Python](https://capmonster-python.alperenn.com/)
- [ESPHome Devices](https://devices.esphome.io/)
- [Label U](https://opendatalab.github.io/labelU-Kit/)
- [React Observing](https://react-observing.web.app/)
- [RudderStack Docs](https://rudderstack.com/docs/)
- [Unform](https://unform.dev)
- [Use Pandas](https://www.usepandas.com/)
- [golangci-lint](https://golangci-lint.run/)
- [use-cloudinary](https://use-cloudinary.netlify.app/)
ps: are you using this project? Submit a PR to add it to the [list](https://github.com/jpedroschmitz/rocketdocs/blob/main/examples/gatsby-theme-docs/src/docs/faq.mdx#what-are-good-examples-of-the-theme-usage).
================================================
FILE: examples/gatsby-theme-docs/src/docs/getting-started.mdx
================================================
---
title: 'Getting started'
description: Learn how to get started with Rocket Docs.
---
> Rocket Docs is ready for Gatsby v5. New projects will use the new version!
The best way to start is by using our starter:
```bash
npx gatsby new rocketdocs https://github.com/jpedroschmitz/gatsby-starter-rocketdocs
```
But, if you prefer, you can install and configure manually.
#### Using Yarn:
```bash
yarn add @rocketseat/gatsby-theme-docs
```
#### Using NPM:
```bash
npm i @rocketseat/gatsby-theme-docs
```
## Theme Options
| Key | Default | Required | Description |
| ------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| basePath | / | No | Root url for all docs |
| configPath | config | No | Location of config files |
| docsPath | docs | No | The site description for SEO and social (FB, Twitter) tags |
| homePath | - | No | Location of home file |
| githubUrl | - | - | Deprecated in favor of `repositoryUrl` |
| repositoryUrl | - | No | The complete URL of your repository (supports GitHub, GitLab and Bitbucket). Example: `https://github/jpedroschmitz/rocketdocs` |
| baseDir | - | No | If your Gatsby site does not live in the root of your project directory/git repo, pass the subdirectory name here (ex: `docs`) |
| withMdx | true | No | If necessary, you can add your own MDX options to the theme. To do so, make sure you turn this option to false and include `gatsby-plugin-mdx` on your `gatsby-config` |
| branch | main | No | Default branch of the repository |
> Note: When adding a BitBucket link on the `repositoryUrl` option, don't add the `src/` to it.
> Example of correct link:
`https://bitbucket.org/jpedroschmitz/rocketdocs`
## Example usage
```js title=gatsby-config.js
module.exports = {
siteMetadata: {
siteTitle: `@rocketseat/gatsby-theme-docs`,
defaultTitle: `@rocketseat/gatsby-theme-docs`,
siteTitleShort: `gatsby-theme-docs`,
siteDescription: `Out of the box Gatsby Theme for creating documentation websites easily and quickly`,
siteUrl: `https://rocketdocs.netlify.app`,
siteAuthor: `@jpedroschmitz`,
siteImage: `/banner.png`,
siteLanguage: `en`,
themeColor: `#8257E6`,
basePath: `/`,
},
plugins: [
{
resolve: `@rocketseat/gatsby-theme-docs`,
options: {
basePath: `/`,
configPath: `src/config`,
docsPath: `src/docs`,
homePath: `src/home`,
repositoryUrl: `https://github.com/jpedroschmitz/rocketdocs`,
baseDir: `examples/gatsby-theme-docs`,
},
},
],
};
```
Once you have installed the dependencies you will need to create the [navigation](/usage/navigation) and [documentation](/usage/creating-docs) files.
================================================
FILE: examples/gatsby-theme-docs/src/docs/usage/creating-docs.mdx
================================================
---
title: Creating docs
description: Learn how to create docs using Rocket Docs.
---
All MDX files created inside your docs folder will become pages, with the path defined by the filename.
Inside all docs files, you can define the following options:
| Key | Required | Description |
| ---------------------- | -------- | -------------------------- |
| title | Yes | No |
| description | No | Page description |
| image | No | Used for og:image |
| disableTableOfContents | No | Disables Table Of Contents |
## Example
```mdx
---
title: 'My Example'
description: 'A simple description for this page'
image: /banner.jpeg
disableTableOfContents: false
---
Wow, this is a nice page
```
## Embedding files
In a documentation website, sometimes you will need to embed well known services (like CodeSandbox, Twitter, or others...). If you need to
do it, you can simply copy-paste the link (powered by the awesome [gatsby-remark-embeder](https://www.gatsbyjs.com/packages/gatsby-remark-embedder/)).
Make sure to check the [supported services](https://github.com/MichaelDeBoey/gatsby-remark-embedder#supported-services).
https://youtu.be/QfcozcbDhNM
## Code Highlight
We support many options for code components.
### Title
To show a title, just add it to your code block. Ex: `title=src/myfile.css`
```css title=src/myfile.css
.gatsby::before {
content: 'niceee...';
}
```
### Line numbers
To add line numbers for that code block, pass an option `lineNumbers=true`.
```js lineNumbers=true
const rocket = {
launch: () => console.log('Launching...'),
};
rocket.launch();
```
### React live
As mentioned in the introduction, this theme uses `react-live`, so you can
create a playground for live editing React components.
To use it, just add a `live=true` option to your code block.
```jsx lineNumbers=true title=gatsby-config.js live=true
function MyComponent() {
function handleButtonClick() {
alert('wowww');
}
return ;
}
render(
);
export default Logo;
```
## Changing the home text
Create a file at `src/docs/index.mdx` with the text. Next, add the `homePath: 'src/home'` setting in the plugin options. Example:
```mdx title=src/docs/index.mdx
# Introduction
My awesome project!
import Navigation from '@rocketseat/gatsby-theme-docs/src/components/Docs/PostNav';
[Get started now!](/getting-started)
================================================
FILE: examples/gatsby-theme-docs/src/pages/404.js
================================================
import React from 'react';
import { Link } from 'gatsby';
import Layout from '@rocketseat/gatsby-theme-docs/src/components/Layout';
import Seo from '@rocketseat/gatsby-theme-docs/src/components/SEO';
export default function NotFound() {
return (
You just hit a route that doesn't exist... the sadness.
If you'd like to go back to homepage, click here
.
);
}
================================================
FILE: examples/gatsby-theme-docs/src/yamlFiles/letters.yml
================================================
- character: a
- character: b
- character: c
================================================
FILE: package.json
================================================
{
"name": "root",
"private": true,
"scripts": {
"lint": "eslint --ignore-path .gitignore \"**/*.+(ts|js|tsx|jsx)\"",
"format": "prettier --ignore-path .gitignore \"**/*.+(ts|js|tsx|jsx)\" --write",
"postinstall": "husky install",
"changeset": "changeset",
"version-packages": "changeset version",
"release": "changeset publish",
"commit": "cz"
},
"engines": {
"node": ">=14.15.0"
},
"workspaces": [
"@rocketseat/*",
"examples/*"
],
"lint-staged": {
"**/*.{ts,js,jsx,tsx}": [
"yarn lint --fix",
"yarn format"
],
"*.{md,mdx,json,yaml}": [
"prettier \"**/*.{md,mdx,json,yaml}\" --write"
]
},
"config": {
"commitizen": {
"path": "cz-conventional-changelog"
}
},
"devDependencies": {
"@changesets/changelog-github": "^0.4.0",
"@changesets/cli": "^2.14.1",
"@commitlint/cli": "16.3.0",
"@commitlint/config-conventional": "16.2.4",
"commitizen": "4.2.4",
"cz-conventional-changelog": "3.3.0",
"eslint": "8.15.0",
"eslint-config-airbnb": "19.0.4",
"eslint-config-prettier": "8.5.0",
"eslint-plugin-import": "2.26.0",
"eslint-plugin-jsx-a11y": "6.5.1",
"eslint-plugin-prettier": "4.0.0",
"eslint-plugin-react": "7.29.4",
"eslint-plugin-react-hooks": "4.5.0",
"eslint-utils": "^3.0.0",
"husky": "7.0.4",
"lint-staged": "12.4.1",
"prettier": "2.6.2"
}
}