gitdocs
gitdocs copied to clipboard
vectordotdev
Customizing the theme
The Problem
We want to have the ability to customize the look of the theme, as well as create a custom theme by changing entire layouts. Currently the theme has hard-coded values for everything, but it should allow custom theme options to be passed from the config file.
Overriding theme attributes
You should be able to pass through a theme object in the config file (.gitdocs.json) that contains simple overrides for visual components such as colors, margins/padding, backgrounds, fonts, etc. The theme should pull these values in from the config prop that gets passed, and use them if they exist--falling back to default values.
Overriding theme layout
The theme uses components for each part of the site such as Navigation, Searchbar, Page, etc. I should be able to customize these components by adding files to the project_root/.components folder with a predefined name. GitDocs should use these instead of the default components if they exist. This allows us to customize certain aspects of the theme, without having to override everything.
Using external theme
GitDocs currently uses its own theme located at ./themes, but you should be able to pass through a value in the config file to define the location (or package name) of a custom theme app. The idea is that you could install an app from NPM called gitdocs-theme-timber, and put "theme": "timber" in your config file to use it.
An external theme can be as simple as a theme object defining visual components, or as complex as custom components for every part of the site. An external theme might look something like this:
components/
Searchbar.js
NavItem.js
TableOfContents.js
Loading.js
Logo.js
layout/
Page.js
Sidebar.js
Header.js
theme.json
Each custom component should receive sub-components via props that are needed to build the layout, similar to a templating language.
layout/Page.js
class Page extends Component {
render () {
const {
TableOfContents,
Body,
} = this.props
return (
<div>
<TableOfContents />
<h1>A Custom Header</h1>
<Body />
</div>
)
}
}
Some Context
What happens when I run gitdocs serve or gitdocs build?
- Some pre-build steps occur (such as dealing with static assets, codegen, etc.)
- The filesystem is walked from the root directory, creating a file tree object
- The file tree is hydrated by reading the front matter of each file, generating titles, fetching sources/cloning git repos, etc.
- The resulting object (the manifest) represents the structure of the GitDocs site. This, along with the user config, gets passed to the theme React app as props.
- The React app parses the manifest and creates routes, navigation, etc. It is bundled through webpack, and either a local server is started (
serve) or the app is statically rendered and outputted to HTML files (build).
One thought on this is that it would be nice to support scoped themes as well (i.e. @org/name) should also work and resolve to @org/gitdocs-theme-name.
I ran into this problem when using gitbook. I wanted a private NPM package for the theme and it's relatively easy to make NPM load all packages in a scope from a different NPM server. However, gitbook requires that all themes begin with gitbook-plugin-theme and can't deal with a scoped theme package.
Totally agree @etimberg. I would opt for the way eslint does it--putting "theme": "name" in the config and resolving to either gitdocs-theme-name or @name/gitdocs-theme.
+1
I understand theme is a better way to customize the docs. Is there any quick way to customize element in the UI?
