Skip to content

Commit c470ed3

Browse files
timlrxtimlrx
authored
Merge pull request #785 from timlrx/faq
add separate FAQ section
2 parents e75cc62 + 02ce094 commit c470ed3

File tree

4 files changed

+232
-131
lines changed

4 files changed

+232
-131
lines changed

‎README.md‎

Lines changed: 6 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -251,146 +251,21 @@ See [Next.js on Netlify](https://docs.netlify.com/integrations/frameworks/next-j
251251

252252
1. Add `output: 'export'` in `next.config.js`. See [static exports documentation](https://nextjs.org/docs/app/building-your-application/deploying/static-exports#configuration) for more information.
253253
2. Comment out `headers()` from `next.config.js`.
254-
3. Change `components/Image.tsx` to use a standard `<img>` tag instead of `next/image`:
255-
256-
```ts
257-
/* eslint-disable jsx-a11y/alt-text */
258-
/* eslint-disable @next/next/no-img-element */
259-
import NextImage, { ImageProps } from 'next/image'
260-
261-
// @ts-ignore
262-
const Image = ({ ...rest }: ImageProps) => <img {...rest} />
263-
264-
export default Image
265-
```
254+
3. Add `unoptimized: true` to the `images` key in `next.config.js`:
266255

267256
Alternatively, to continue using `next/image`, you can use an alternative image optimization provider such as Imgix, Cloudinary or Akamai. See [image optimization documentation](https://nextjs.org/docs/app/building-your-application/deploying/static-exports#image-optimization) for more details.
268257

269258
4. Remove `api` folder and components which call the server-side function such as the Newsletter component. Not technically required and the site will build successfully, but the APIs cannot be used as they are server-side functions.
270259
5. Run `yarn build`. The generated static content is in the `out` folder.
271260
6. Deploy the `out` folder to your hosting service of choice or run `npx serve out` to view the website locally.
272261

273-
## Frequently Asked Questions
274-
275-
### How can I add a custom MDX component?
276-
277-
Here's an example on how to create a donut chart from Chart.js (assuming you already have the dependencies installed) and use it in MDX posts. First, create a new `DonutChart.tsx` component in `components`:
278-
279-
```tsx
280-
'use client'
281-
282-
import { Doughnut } from 'react-chartjs-2'
283-
import { Chart as ChartJS, ArcElement, Tooltip, Legend } from 'chart.js'
284-
285-
ChartJS.register(ArcElement, Tooltip, Legend)
286-
287-
const DonutChart = ({ data }) => {
288-
return <Doughnut data={data} />
289-
}
262+
__Note__: Deploying on Github pages require addition modifications to the base path. Please refer to the FAQ for more information.
290263

291-
export default Doughnut
292-
```
293-
294-
Since the underlying `Doughnut` component uses React hooks, we add the `'use client'` directive to specify that it is a client side component. Also, there is an existing issue which prevents named components from being used, so we need to export the component as the default export.
295-
296-
Next, add the component to `MDXComponents.tsx`:
297-
298-
```diff
299-
...
300-
+ import DonutChart from './DonutChart'
301-
302-
export const components: MDXComponents = {
303-
Image,
304-
TOCInline,
305-
a: CustomLink,
306-
pre: Pre,
307-
+ DonutChart,
308-
BlogNewsletterForm,
309-
}
310-
```
311-
312-
You can now use the component in `.mdx` files:
313-
314-
```mdx
315-
## Example Donut Chart
316-
317-
export const data = {
318-
labels: ['Red', 'Blue', 'Yellow'],
319-
datasets: [
320-
{
321-
label: '# of Votes',
322-
data: [12, 19, 3],
323-
backgroundColor: [
324-
'rgba(255, 99, 132, 0.2)',
325-
'rgba(54, 162, 235, 0.2)',
326-
'rgba(255, 206, 86, 0.2)',
327-
],
328-
borderColor: ['rgba(255, 99, 132, 1)', 'rgba(54, 162, 235, 1)', 'rgba(255, 206, 86, 1)'],
329-
borderWidth: 1,
330-
},
331-
],
332-
}
333-
334-
<DonutChart data={data} />
335-
```
264+
## Frequently Asked Questions
336265

337-
### How can I customize the `kbar` search?
338-
339-
Add a `SearchProvider` component such as the one shown below and use it in place of the default `SearchProvider` component in `app/layout.tsx`.
340-
341-
`defaultActions` are the initial list of actions.
342-
343-
`onSearchDocumentsLoad` is a callback function that is called when the documents specified by `searchDocumentsPath` are loaded. Set `searchDocumentsPath` to `false` to disable the dynamically loaded search feature.
344-
345-
```tsx
346-
'use client'
347-
348-
import { KBarSearchProvider } from 'pliny/search/KBar'
349-
import { useRouter } from 'next/navigation'
350-
import { CoreContent } from 'pliny/utils/contentlayer'
351-
import { Blog } from 'contentlayer/generated'
352-
353-
export const SearchProvider = ({ children }) => {
354-
const router = useRouter()
355-
return (
356-
<KBarSearchProvider
357-
kbarConfig={{
358-
searchDocumentsPath: 'search.json',
359-
defaultActions: [
360-
{
361-
id: 'homepage',
362-
name: 'Homepage',
363-
keywords: '',
364-
shortcut: ['h', 'h'],
365-
section: 'Home',
366-
perform: () => router.push('/'),
367-
},
368-
{
369-
id: 'projects',
370-
name: 'Projects',
371-
keywords: '',
372-
shortcut: ['p'],
373-
section: 'Home',
374-
perform: () => router.push('/projects'),
375-
},
376-
],
377-
onSearchDocumentsLoad(json) {
378-
return json.map((post: CoreContent<Blog>) => ({
379-
id: post.path,
380-
name: post.title,
381-
keywords: post?.summary || '',
382-
section: 'Blog',
383-
subtitle: post.tags.join(', '),
384-
perform: () => router.push(post.path),
385-
}))
386-
},
387-
}}
388-
>
389-
{children}
390-
</KBarSearchProvider>
391-
)
392-
}
393-
```
266+
- [How can I add a custom MDX component?](/faq/custom-mdx-component.md)
267+
- [How can I customize the `kbar` search?](/faq/customize-kbar-search.md)
268+
- [How do I deploy on Github pages?](/faq/github-pages-deployment.md)
394269

395270
## Support
396271

‎faq/custom-mdx-component.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# How can I add a custom MDX component?
2+
3+
Here's an example on how to create a donut chart from Chart.js (assuming you already have the dependencies installed) and use it in MDX posts. First, create a new `DonutChart.tsx` component in `components`:
4+
5+
```tsx
6+
'use client'
7+
8+
import { Doughnut } from 'react-chartjs-2'
9+
import { Chart as ChartJS, ArcElement, Tooltip, Legend } from 'chart.js'
10+
11+
ChartJS.register(ArcElement, Tooltip, Legend)
12+
13+
const DonutChart = ({ data }) => {
14+
return <Doughnut data={data} />
15+
}
16+
17+
export default Doughnut
18+
```
19+
20+
Since the underlying `Doughnut` component uses React hooks, we add the `'use client'` directive to specify that it is a client side component. Also, there is an existing issue which prevents named components from being used, so we need to export the component as the default export.
21+
22+
Next, add the component to `MDXComponents.tsx`:
23+
24+
```diff
25+
...
26+
+ import DonutChart from './DonutChart'
27+
28+
export const components: MDXComponents = {
29+
Image,
30+
TOCInline,
31+
a: CustomLink,
32+
pre: Pre,
33+
+ DonutChart,
34+
BlogNewsletterForm,
35+
}
36+
```
37+
38+
You can now use the component in `.mdx` files:
39+
40+
```mdx
41+
## Example Donut Chart
42+
43+
export const data = {
44+
labels: ['Red', 'Blue', 'Yellow'],
45+
datasets: [
46+
{
47+
label: '# of Votes',
48+
data: [12, 19, 3],
49+
backgroundColor: [
50+
'rgba(255, 99, 132, 0.2)',
51+
'rgba(54, 162, 235, 0.2)',
52+
'rgba(255, 206, 86, 0.2)',
53+
],
54+
borderColor: ['rgba(255, 99, 132, 1)', 'rgba(54, 162, 235, 1)', 'rgba(255, 206, 86, 1)'],
55+
borderWidth: 1,
56+
},
57+
],
58+
}
59+
60+
<DonutChart data={data} />
61+
```

‎faq/customize-kbar-search.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# How can I customize the `kbar` search?
2+
3+
Add a `SearchProvider` component such as the one shown below and use it in place of the default `SearchProvider` component in `app/layout.tsx`.
4+
5+
`defaultActions` are the initial list of actions.
6+
7+
`onSearchDocumentsLoad` is a callback function that is called when the documents specified by `searchDocumentsPath` are loaded. Set `searchDocumentsPath` to `false` to disable the dynamically loaded search feature.
8+
9+
```tsx
10+
'use client'
11+
12+
import { KBarSearchProvider } from 'pliny/search/KBar'
13+
import { useRouter } from 'next/navigation'
14+
import { CoreContent } from 'pliny/utils/contentlayer'
15+
import { Blog } from 'contentlayer/generated'
16+
17+
export const SearchProvider = ({ children }) => {
18+
const router = useRouter()
19+
return (
20+
<KBarSearchProvider
21+
kbarConfig={{
22+
searchDocumentsPath: 'search.json',
23+
defaultActions: [
24+
{
25+
id: 'homepage',
26+
name: 'Homepage',
27+
keywords: '',
28+
shortcut: ['h', 'h'],
29+
section: 'Home',
30+
perform: () => router.push('/'),
31+
},
32+
{
33+
id: 'projects',
34+
name: 'Projects',
35+
keywords: '',
36+
shortcut: ['p'],
37+
section: 'Home',
38+
perform: () => router.push('/projects'),
39+
},
40+
],
41+
onSearchDocumentsLoad(json) {
42+
return json.map((post: CoreContent<Blog>) => ({
43+
id: post.path,
44+
name: post.title,
45+
keywords: post?.summary || '',
46+
section: 'Blog',
47+
subtitle: post.tags.join(', '),
48+
perform: () => router.push(post.path),
49+
}))
50+
},
51+
}}
52+
>
53+
{children}
54+
</KBarSearchProvider>
55+
)
56+
}
57+
```

‎faq/github-pages-deployment.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# How do I deploy on Github pages?
2+
3+
[Demo](https://timlrx.github.io/tailwind-nextjs-starter-blog/) & [Source](https://github.com/timlrx/tailwind-nextjs-starter-blog/tree/test-gh-pages-static)
4+
5+
1. Follow the section on creating a static build in the main README and test it locally to ensure that it works.
6+
2. Specify the base path in `next.config.js` to match your repository name e.g. `basePath: "/tailwind-nextjs-starter-blog"`.
7+
3. Modify `component/Image.tsx` to use the correct base path for the image source:
8+
9+
```tsx
10+
import NextImage, { ImageProps } from 'next/image'
11+
12+
const Image = ({ src, ...rest }: ImageProps) => (
13+
<NextImage src={`/tailwind-nextjs-starter-blog${src}`} {...rest} />
14+
)
15+
16+
export default Image
17+
```
18+
19+
4. To automate deployment, here's a Github action that you could use
20+
21+
```yml
22+
# Sample workflow for building and deploying a Next.js site to GitHub Pages
23+
#
24+
# To get started with Next.js see: https://nextjs.org/docs/getting-started
25+
#
26+
name: Deploy Next.js site to Pages
27+
28+
on:
29+
# Runs on pushes targeting the default branch
30+
push:
31+
branches: ['test-gh-pages-static']
32+
33+
# Allows you to run this workflow manually from the Actions tab
34+
workflow_dispatch:
35+
36+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
37+
permissions:
38+
contents: read
39+
pages: write
40+
id-token: write
41+
42+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
43+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
44+
concurrency:
45+
group: 'pages'
46+
cancel-in-progress: false
47+
48+
jobs:
49+
# Build job
50+
build:
51+
name: Build Nextjs Blog
52+
runs-on: ubuntu-latest
53+
steps:
54+
- name: Checkout
55+
uses: actions/checkout@v3
56+
- name: Detect package manager
57+
id: detect-package-manager
58+
run: |
59+
if [ -f "${{ github.workspace }}/yarn.lock" ]; then
60+
echo "manager=yarn" >> $GITHUB_OUTPUT
61+
echo "command=install" >> $GITHUB_OUTPUT
62+
echo "runner=yarn" >> $GITHUB_OUTPUT
63+
exit 0
64+
elif [ -f "${{ github.workspace }}/package.json" ]; then
65+
echo "manager=npm" >> $GITHUB_OUTPUT
66+
echo "command=ci" >> $GITHUB_OUTPUT
67+
echo "runner=npx --no-install" >> $GITHUB_OUTPUT
68+
exit 0
69+
else
70+
echo "Unable to determine package manager"
71+
exit 1
72+
fi
73+
- name: Setup Node
74+
uses: actions/setup-node@v3
75+
with:
76+
node-version: '18'
77+
cache: ${{ steps.detect-package-manager.outputs.manager }}
78+
- name: Restore cache
79+
uses: actions/cache@v3
80+
with:
81+
path: |
82+
.next/cache
83+
# Generate a new cache whenever packages or source files change.
84+
key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
85+
# If source files changed but packages didn't, rebuild from a prior cache.
86+
restore-keys: |
87+
${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-
88+
- name: Install dependencies
89+
run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }}
90+
- name: Build project assets
91+
run: ${{ steps.detect-package-manager.outputs.manager }} build
92+
- name: Upload artifact
93+
uses: actions/upload-pages-artifact@v2
94+
with:
95+
path: ./out
96+
97+
# Deployment job
98+
deploy:
99+
environment:
100+
name: github-pages
101+
url: ${{ steps.deployment.outputs.page_url }}
102+
runs-on: ubuntu-latest
103+
needs: build
104+
steps:
105+
- name: Deploy to GitHub Pages
106+
id: deployment
107+
uses: actions/deploy-pages@v2
108+
```

0 commit comments

Comments
 (0)