1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
---
title: Getting Started
layout: ~/layouts/MainLayout.astro
---
This template already provides your pages with a side bar navigation (on the left) for your pages, and a content navigation (on the right) for your sections.
## Page navigation
The page navigation, through the side bar on the left, needs to be manually updated. Open the `config.ts` file and you will find the following structure:
```ts
export const SIDEBAR = {
en: [
{ text: 'Getting Started', header: true },
{ text: 'Introduction', link: 'en/introduction' },
{ text: 'Getting Started', link: 'en/getting-started' },
{ text: 'Example', link: 'en/example' },
],
es: [
{ text: 'Empezando', header: true },
{ text: 'Introducción', link: 'es/introduction' },
{ text: 'Empezando', link: 'es/getting-started' },
{ text: 'Ejemplo', link: 'es/example' },
],
fr: [
{ text: 'Commencer', header: true },
{ text: 'Introduction', link: 'fr/introduction' },
{ text: 'Commencer', link: 'fr/getting-started' },
{ text: 'Exemple', link: 'fr/example' },
],
};
```
The sidebar supports many languages, and each language has items to display, and pages to link to, allowing for a truly native experience for international users. You can change this file to match the pages you want to display, the object with the `{ header: true, ... }` set to true will act as a section title and cannot contain a link.
The page navigation is generated in the `src/components/LeftSidebar/LeftSidebar.astro`, so if you want to change the depth of elements displayed, styles, etc, that's the place to go.
## Section navigation
The section navigation, through the side bar on the right, is automatically generated by the `src/components/RightSidebar/RightSidebar.astro` file, it uses the meta-data from markdown files to generate the structure you see.
By default only elements from depth 2 to 5 will be displayed, and at the moment doesn't work for `.astro files`.
## Other Components
### Footer
You can edit your footer here `src/components/Footer/Footer.astro`, at the moment it is composed of a list of avatars. You can generate your own avatar [here](https://getavataaars.com/) and replace the ones from `src/components/Footer/AvatarList.astro`.
### Theme
The `src/components/RightSidebar/ThemeToggleButton.tsx` is only responsible for applying the theme, to change the theme colors see `public/theme.css`
## Multiple Languages
By default the Astro docs template encourages writing your docs in mutliple languages, it also encourages writing your docs in a specific file structure
```
📦pages
┣ 📂en
┃ ┣ 📜example.md
┃ ┣ 📜getting-started.md
┃ ┣ 📜index.astro
┃ ┗ 📜introduction.md
┣ 📂es
┃ ┣ 📜example.md
┃ ┣ 📜getting-started.md
┃ ┣ 📜index.astro
┃ ┗ 📜introduction.md
┣ 📂fr
┃ ┣ 📜example.md
┃ ┣ 📜getting-started.md
┃ ┣ 📜index.astro
┃ ┗ 📜introduction.md
┗ 📜index.astro
```
each folder within the `pages/` folder represents a language, to add new languages, you will need to create a new langauge folder,
add the langauges name to the `LANGUAGE_NAMES` variable in the [`languages.ts`](../../languages.ts) file, and add new sidebar links corrosponding to the new language. E.g. Adding Deutsch as a supported language
1. Create the `de/` folder in the pages directory
```
📦pages
┣ 📂en
┃ ┣ 📜example.md
┃ ┣ 📜getting-started.md
┃ ┣ 📜index.astro
┃ ┗ 📜introduction.md
┣ 📂de
┃ ┣ 📜example.md
┃ ┣ 📜getting-started.md
┃ ┣ 📜index.astro
┃ ┗ 📜introduction.md
┗ 📜index.astro
```
2. Add Deutsch to the `LANGUAGE_NAMES` variable in the [`languages.ts`](../../languages.ts) file
```ts
// src/languages.ts
export const LANGUAGE_NAMES = {
English: 'en',
Deutsch: 'de',
};
// ...
```
3. Add Deutch as a localized language for the SIDEBAR
```ts
// src/config.ts
export const SIDEBAR = {
en: [
{ text: 'Getting Started', header: true },
{ text: 'Introduction', link: 'en/introduction' },
{ text: 'Getting Started', link: 'en/getting-started' },
{ text: 'Example', link: 'en/example' },
],
de: [
{ text: 'Einstieg', header: true },
{ text: 'Einführung', link: 'de/introduction' },
{ text: 'Einstieg', link: 'de/getting-started' },
{ text: 'Beispiel', link: 'de/example' },
],
};
// ...
```
> _**Note**: make sure the sidebar links point to the proper language folder_
<!-- , but if you are unable to properly support multiple languages, you can disable multiple languages, you set the `DISABLE_MULTIPLE_LANGUAGES` variable in the [`config.ts`](../../config.ts) file to `true`, but you still need to change and tweak a couple more things.
After settings `DISABLE_MULTIPLE_LANGUAGES` you can now move the pages from the language folder you wish to use, e.g. I speak english, so, I would delete every other folders and files in the [`pages/`](../) folder except for the [`en/`](./) folder, I would then move the files from the [`en/`](./) folder to the [`pages/`](../) folder, delete all `index.astro` files, and finally delete the [`en/`](./) folder.
The file structure will look like this once you are done,
```
📦src
┣ 📂components
┃ ┣ ...
┣ 📂layouts
┃ ┗ 📜MainLayout.astro
┣ 📂pages
┃ ┣ 📜example.md
┃ ┣ 📜getting-started.md
┃ ┗ 📜introduction.md
┣ 📜config.ts
┗ 📜languages.ts
```
You will then need to rename `introductions.md` to `index.md`, and reorganize the `SIDEBAR` variable in the [`config.ts`](../../config.ts) file to resemble something like this (remember to change the links, since the `en/` folder has been deleted),
```ts
export const SIDEBAR = [
// index.md is the homepage, so, you don't need to set a sidebar link
{ text: 'Introduction', header: true },
{ text: 'Getting Started', link: 'getting-started' },
{ text: 'Example', link: 'example' },
]
```
and that's it. -->
## Algolia DocSearch
[Algolia](https://www.algolia.com/) offers [DocSearch](https://docsearch.algolia.com/), a _"State-of-the-art search for technical documentation"_. We use DocSearch for the Astro docs as it's a great documentation search engine, to make things setting up docs easier we built it into the docs template, you can setup DocSearch for your site by following these instructions, ...
### 🛠 Configuration
...
## Documentation
For more information on how to use Astro components, check the documentation pages:
- [Quick Start](https://docs.astro.build/quick-start)
- [astro.config.mjs](https://docs.astro.build/reference/configuration-reference)
- [API](https://docs.astro.build/reference/api-reference)
- [Command Line Interface](https://docs.astro.build/reference/cli-reference)
- [Collections](https://docs.astro.build/core-concepts/collections)
- [Development Server](https://docs.astro.build/reference/dev/)
- [Markdown](https://docs.astro.build/guides/markdown-content)
- [Publishing Astro components](https://docs.astro.build/guides/publish-to-npm)
- [Renderers](https://docs.astro.build/reference/renderer-reference)
- [Styling](https://docs.astro.build/guides/styling)
- [.astro Syntax](https://docs.astro.build/core-concepts/astro-components)
|
