Skip to content

Commit e1af64b

Browse files
roydukkeyroydukkey
committed
Initial release!
1 parent 3e4b546 commit e1af64b

21 files changed

+597
-1
lines changed

‎.editorconfig‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# editorconfig.org
2+
root = true
3+
4+
[*]
5+
charset = utf-8
6+
indent_size = 2
7+
indent_style = tab
8+
tab_width = 2
9+
trim_trailing_whitespace = true
10+
end_of_line = lf
11+
insert_final_newline = true
12+
13+
[*.{md,mdx}]
14+
indent_style = space

‎.github/FUNDING.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# These are supported funding model platforms
2+
3+
github: [roydukkey]

‎.gitignore‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# User-specific files
2+
.DS_Store
3+
*.vs
4+
*.user
5+
6+
# Package Managers
7+
node_modules
8+
npm-debug.log
9+
10+
# Build Artifacts
11+
*.lock.json
12+
*-lock.json
13+
*.lock
14+
*.backup
15+
*.cache
16+
*.jest
17+
*.tgz
18+
dist
19+
package

‎.npmignore‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# User-specific files
2+
.DS_Store
3+
*.editorconfig
4+
*.env
5+
*.user
6+
*.vs
7+
*.vscode
8+
*.github
9+
10+
# Package Managers
11+
node_modules
12+
npm-debug.log
13+
14+
# Build Artifacts
15+
*.lock.json
16+
*-lock.json
17+
*.backup
18+
*.cache
19+
*.tgz
20+
21+
# Source Code
22+
tsconfig*

‎.vscode/cSpell.json‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"version": "0.2",
3+
"ignorePaths": [
4+
"node_modules",
5+
".git",
6+
".jest",
7+
".docusaurus",
8+
"**/.DS_Store",
9+
"*.lock.json",
10+
"*-lock.json",
11+
"*.lock",
12+
"*.tgz",
13+
"*.svg"
14+
],
15+
"dictionaries": [
16+
"fullstack"
17+
],
18+
// Before adding a word, see if there is already a dictionary in which it is contained.
19+
// http://github.com/streetsidesoftware/cspell-dicts
20+
"words": [
21+
"graymatter",
22+
"roydukkey",
23+
"streetsidesoftware",
24+
"tsdoc"
25+
]
26+
}

‎.vscode/extensions.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
// See http://go.microsoft.com/fwlink/?LinkId=827846
3+
// for the documentation about the extensions.json format
4+
"recommendations": [
5+
"editorconfig.editorconfig",
6+
"streetsidesoftware.code-spell-checker"
7+
]
8+
}

‎.vscode/settings.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"files.exclude": {
3+
"**/node_modules": true,
4+
"package-lock.json": true,
5+
"yarn.lock": true
6+
}
7+
}

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Changelog
2+
3+
<!-- The order of list items should be: Critical/Fixes, New, Update, Remove, Underpinnings -->
4+
<!-- ## [UNRELEASED](https://github.com/roydukkey/docusaurus-theme-frontmatter/compare/v1.0.0...master) -->
5+
6+
## 1.0.0
7+
8+
* Initial release!

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2022 trent
3+
Copyright (c) 2022 roydukkey
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# docusaurus-theme-frontmatter
2+
3+
This package enhances the Docusaurus classic theme by exposing the [docs](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-frontmatter), [blog](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog#markdown-frontmatter), and [pages](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-pages) front matter to the following components and their children:
4+
5+
* [BlogPostItem](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme/BlogPostItem)
6+
* [DocItem](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme/DocItem)
7+
* [MDXPage](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme/MDXPage)
8+
9+
Furthermore, this allows you to define and access ***custom*** front matter.
10+
11+
## Install
12+
13+
```sh
14+
yarn add docusaurus-theme-frontmatter
15+
```
16+
17+
Then, include the plugin in your `docusaurus.config.js` file.
18+
19+
```diff
20+
// docusaurus.config.js
21+
module.exports = {
22+
...
23+
+ themes: ['docusaurus-theme-frontmatter'],
24+
...
25+
}
26+
```
27+
28+
### TypeScript support
29+
30+
To enable TypeScript support, the TypeScript configuration should be updated to add the `docusaurus-theme-frontmatter` type definitions. This can be done in the `tsconfig.json` file:
31+
32+
```diff
33+
{
34+
"extends": "@tsconfig/docusaurus/tsconfig.json",
35+
"compilerOptions": {
36+
...
37+
+ "types": ["docusaurus-theme-frontmatter"]
38+
}
39+
}
40+
```
41+
42+
## How to use
43+
44+
The `useFrontMatter()` hook is made available to any of your components through the `@theme/useFrontMatter` import. For example, you might have a component that creates a gallery of images.
45+
46+
```mdx
47+
---
48+
title: Miniature fairy doors of NYC
49+
hide_table_of_contents: true
50+
gallery:
51+
- /images/117-first-avenue.jpg
52+
- /images/lower-east-side.jpg
53+
- /images/my-guinness.jpg
54+
- /images/hundred-years.jpg
55+
---
56+
import Galley from '@theme/Galley';
57+
58+
<Galley />
59+
```
60+
61+
```jsx
62+
import React from 'react';
63+
import ImageGallery from 'react-image-gallery';
64+
import useFrontMatter from '@theme/useFrontMatter';
65+
66+
export default function GalleyComponent () {
67+
const { gallery } = useFrontMatter();
68+
69+
if (Array.isArray(gallery)) {
70+
const images = gallery.map((image) => ({
71+
original: image
72+
}));
73+
74+
return <ImageGallery items={images} />;
75+
}
76+
77+
return null;
78+
}
79+
```
80+
81+
## Public API
82+
83+
### `useFrontMatter<T extends FrontMatter>()`
84+
85+
Returns the front matter for the current context.
86+
87+
```ts
88+
import useFrontMatter from '@theme/useFrontMatter';
89+
90+
interface CustomFrontMatter {
91+
gallery?: string[];
92+
}
93+
94+
const MyComponent = () => {
95+
const { gallery } = useFrontMatter<CustomFrontMatter>();
96+
return (<... />);
97+
}
98+
```
99+
100+
### `Context`
101+
102+
The current front matter context.
103+
104+
Generally, this is something to be left alone and operates behind the scenes. This is how it is used to [enhance DocItem](https://github.com/roydukkey/docusaurus-theme-frontmatter/blob/master/src/theme/DocItem.tsx) scaffolding the hook:
105+
106+
```js
107+
import { Context } from '@theme/useFrontMatter';
108+
import DocItem from '@theme-init/DocItem';
109+
import React from 'react';
110+
111+
export default (props) => <Context.Provider value={props.content.frontMatter}>
112+
<DocItem {...props} />
113+
</Context.Provider>;
114+
```
115+
116+
### `FrontMatter`, `DocItemFrontMatter`, `BlogPostItemFrontMatter`, `MDXPageFrontMatter`
117+
118+
These types are provided to assist in describing the values returned by the `useFrontMatter()` hook.
119+
120+
```ts
121+
import useFrontMatter from '@theme/useFrontMatter';
122+
import type { DocItemFrontMatter } from '@theme/useFrontMatter';
123+
124+
const MyComponent = () => {
125+
const { id, title, keywords } = useFrontMatter<DocItemFrontMatter>();
126+
return (<... />);
127+
}
128+
```

0 commit comments

Comments
 (0)