Document Template
Document Template for Markdown content.
Explore the docs »
View Demo
·
Report Bug
·
Request Feature
Table of Contents
About The Project
Built With
Installation
- Clone the repo
git clone https://github.com/centria/template- Install NPM packages
npm install
yarn- Implement application on local server
npm start
yarn start- Lint application with ESLint
npm run lint
yarn run lint- Build application code with
npm run build
yarn run buildGetting Started
Config to deploy the application on Github Pages
To deploy the application on your own Github Pages, first you need create a secret key on your account by going to *account setting then developer settings and personal access tokens and generate new token, tick on repo option as the picture below:
After that, clone this repo as a template for the new repo on your Github account, and make sure mark it as PUBLIC
then go to SETTINGS, choose SECRETS, create New repository secret, name it as TEMPLATE_API and paste the personal access token you created before then click Add secret as the image below:
After that got to the ./gatsby-config.js file on the root folder and adjust the pathPrefix field with your Github repo name. For example, if your app repo name is my-repo then it should be pathPrefix: '/my-repo'.
You also can watch this tutorial if you need more help on this.
Replace document content
To replace document content, you need to delete the content folder in ./src folder then replace your own document content folder.
Types of content
At the moment, the template offers two types of content. The first one is created by the template file, these papges will have the same layout with the main content taken from markdown files in the content folder. Most pages of this template belong to this type. The second one, is the pages create by setup a new file in pages folder. This type of content will have different layouts (or behaviors) compare to the first one depends on the purpose of the developers. At this stage, 404 is the only one page belongs to this type.
About hidden content
In the ./src/content, you will find a hidden-docs folder. This will be the folder contains all of the content that you want them to be hidden likes LICENSE, exercise instructions or exercise solutions. To turn a Markdown file into a hidden file, you just need to set the hidden field in its front matter to be true as below
To access to a hidden file in a Markdown document you can add a Link component, for example, if you want to access to tmc file in the hidden folder, you can add a Link component as below
About License
In the project, you can find that we have two LICENSE files, one is in the foot directory, the other is in the hidden-docs directory. The first one is for Github, and the second one is the one you can access in the Footer section of the page. Both of them are supposed to have the same content.
Update repositories created by the template
When the template get some new features and you also want to update repositories created with this, you can run the command below:
npx update-template https://github.com/centria/templateDocument content structure
Basically, all the markdown files in your content folder will be displayed in the side navbar, except the index file. It will be the main page to display when you visit the application, or you can revisit it by clicking on the Centria's logo. For example, the image bellow is a content folder with three main part, each will have a main folder and a index markdown file corresponding, folder part 1 will have part1.md as its index page. And you can have many single page as you want like exam, exercises, ...
Config content files front matter
In order to display the content from the files, we need to config the front matter data so the app can get its necessary information. Two compulsory fields need to have for each file are title and nav_order. Title will be used to display the part's name in the navbar and nav_order will be used for sorting those name in navbar. Bellow is the frontmatter of part 1.
NOTE
About numbering the nav_order, the data that retrieved from the server will be the same as the order of your nav_order, so make sure you mark every content in a proper order and do not duplicate them. For example, if your mark the Part 1 page with nav_order:1 then the subcontent of Part 1 like Part1-1, Part1-2 will have nav_order as 2, and 3 corresponding and the Part 2 have to have higher order than all the content of Part 1.
TIP
In order to make things easier, my tip is mark each part of content with at least two digits. For example, Part 1 and all its subcontent can be marked as 1*, likes 10, 11, 12... and Part 2 as 2*... That way, you can easy add more extra content later if needed.
Application styling
The global style of this template take reference from Benjamin De Cock and you can find it in ./src/styles/global.js.
To make the application's reponsiveness, the media queries take reference from Gatsby theme Novela, you can adjust it by modifying ./src/styles/media.js. All breakpoints can be found inside of theme.breakpoints and each is turned in to a min + 1 and max-width version.
You can adjust the styles of the application by modifying the file src/gatsby-plugin-theme-ui .
I recommend keep then setting as default since they will have effects to the responsiveness of the application on other platforms. However, you can still adjust the styles of the application by modifying src/gatsby-plugin-theme-ui/color.js
Syntax highlighting
Codeblook highlighting functionality of this app is boostrapping with theme-ui. Althought this is the most popular choice for supporting syntax highlight with Gatsby, it still have its limit and cannot cover all programming languages. However, it can be supported with Prismjs to have more languages withhighlight support, the config can be found here. For instance, if you want the support highlighting for R language, you can adjust the content of src/gatsby-plugin-theme-ui/components.js as
List of supported languages by theme-ui.
The defaut highlighting style used in this application is ocenic, you can choose different highlighting styles from Theme-ui style list
Roadmap
See the open issues for a list of proposed features (and known issues).
Contributing
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
License
Distributed under the MIT License. See LICENSE for more information.