You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You can make a limited range of edits from the Github site! Hooray! But this system works best if you clone it locally so you can run test builds.
47
+
48
+
#### Recommended editors
49
+
50
+
Laura uses Atom because it's got the best merge conflict resolution interface out there. If you use Atom, there are some really helpful packages available for authoring in Markdown.
51
+
- language-markdown
52
+
- markdown-preview
53
+
- markdown-table-editor
54
+
- markdown-toc
55
+
56
+
Some folks use Sublime. (Please add your tips and comments here if you do!)
57
+
58
+
59
+
## Most frequently asked question: Do I need a review?
60
+
61
+
The docs repo works on the honor system right now. The only rule is you can't merge if it breaks the build (or introduces security vulns that Snyk complains about).
62
+
63
+
-**Just fixing a typo**? -> No review needed, merge with blessings.
64
+
65
+
-**Delta of <50 words or ~250 characters**? -> No review needed, but get someone to spot check you just in case.
66
+
67
+
-**Adding new feature docs**? -> Yes. Get _two_ reviewers, one for technical accuracy, and one for copy.
68
+
69
+
## How to docs (The Docs Process)
70
+
71
+
1. Check out the repo and get set up.
72
+
2. Create a new branch and make your changes.
73
+
- Change the content in the files.
74
+
- If needed, update the appropriate file in the `src/_data/sidenav/` to reflect your changes.
75
+
- You can use the `make sidenav` command to generate a yml file from the current structure of your docs, which you can then use to update the nav. This command does not overwrite the nav, you need to manually copy and paste the important bits in.
76
+
3. Commit your changes.
77
+
3. Push the branch to `segment-docs` and make a PR to master.
78
+
- Include any context you can in the PR: links to ZD tickets, Jira tickets, Paper docs or wiki pages about the project. (If you include a Jira ticket number, Jira can often link directly to the PR.)
79
+
3.[Check if you need a review](#most-frequently-asked-question-do-i-need-a-review).
80
+
5. If the reviewers ask for clarifications or edits:
81
+
- make the changes
82
+
- push the new commits to the branch
83
+
5. Once you get a review, and the checks pass, merge your PR.
84
+
6. Once you've merged the branch, delete it!
85
+
86
+
### Long running projects
87
+
88
+
If you're doing a substantial change and you're going to want to spend a few weeks on it, use [Github's Draft PRs feature](https://help.github.com/en/articles/about-pull-requests#draft-pull-requests), or add `WIP` to the title of your PR. This lets us know to ignore the PR until you're ready.
89
+
90
+
## Repo structure
91
+
92
+
All of the content files live in the `/src/` directory. Everything outside of this is related to the build.
93
+
94
+
### Utility files
95
+
Anything that starts with an `_` is a utility directory of some sort (and Jekyll will skip/not render any file that starts with a `_`).
96
+
97
+
The most interesting ones are:
98
+
-`/src/_includes/content/` This is where all the partials - the reusable content - are stored.
99
+
-`/src/_data/catalog/` This is where we keep the data we've pulled from the ConfigAPI in some structured `yml` files that are used by the build.
100
+
-`/src/_data/sidenav/` This is where the navigation structures are. (Several sections in the doc have their own nav, making them "microsites".) They're just YML files that we manually update so we have maximum control.
101
+
102
+
### Content files
103
+
There are folders for each of the top level products, and those folders might also contain topics that are related to that product area (for example the Privacy Portal section also contains GDPR/CCPA docs).
104
+
105
+
For the Connections product, the section is divided into Sources, Destinations, and Warehouses, with general accessory topics at the folder root. (More specific accessory topics are in each sub directory.) Each also contains a `catalog` directory, which contains all the directories with information about specific integrations. The top-level of this folder (the `index.md`) is a pretty "catalog" page which gives a tile-like view by category, suitable for browsing. It pulls the logo for these tiles from the path for the integration in the metadata service.
106
+
107
+
### Intelligent content
108
+
Destinations: These files also include "intelligent partials", which are sections of doc that are built conditionally, or using/based on information from the metadata service. This is *awesome* and like the holy grail of docs systems, so please keep the metadata up to date. Check out the `_includes/content/integration-foot.md` to see this in action. This uses Liquid scripting and pulls from the catalog metadata.
109
+
110
+
111
+
## Formatting and Prettifying
112
+
Some important tips! We also have a Styleguide available so you can see how different formatting looks when rendered.
113
+
114
+
### Adding Images
115
+
116
+
**All images should be saved locally! No linking to 3rd party-hosted images!**
117
+
As CDN hosting is from the publish side, we shouldn't be worrying about that at the file level.
118
+
119
+
To add images to a docs page, create an `images` folder for the docs path, save the image to the folder and then reference it in your markdown file. The [Google Analytics destination](/src/connections/destinations/catalog/google-analytics) is a good example.
120
+
121
+
There are no naming conventions at this time. Anything you see with `asset` was dowloaded by a script to save it from Contents.io. :)
122
+
123
+
## Frontmatter
124
+
125
+
Each Markdown file in the docs can have frontmatter (also and formerly known as "metadata") associated with it at the top of the file. (For clarity, we call it "Frontmatter" to prevent confusion with the Segment "Metadata service".
126
+
127
+
It'll look something like this:
128
+
129
+
```text
130
+
---
131
+
title: Analytics.js Library
132
+
hide-feedback: false
133
+
---
134
+
```
135
+
136
+
Each piece of frontmatter does something special:
137
+
138
+
-`beta`: default false. When true, show an "in beta" warning in the page layout (see the warning in `_includes/content/beta.md`)
139
+
-`hide-feedback`: defaults to false. When true, hide the feedback footer. Good for legal and landing pages.
140
+
-`hidden`: omits the file from the `sitemap.xml`, adds a `<meta name="robots" content="noindex" />` to the top of the generated HTML file, and drops it from the convenience script for regenerating the nav.
141
+
-`rewrite`: defaults to false. This is a legacy frontmatter flag that comes from the old `site-docs` repo, and which labels any destination that was rewritten in ~2018 to a standardized template.
142
+
-`hide_toc`: hides the right-nav TOC that's generated from H2s
143
+
-`integration_type`: This is set in the `_config.yml` on three paths to add a noun (Source, Destination, or Warehouse) to the end of the title, and the end of the title tag in the html layout. It also controls the layout and icon for some of these.
144
+
-`landing`: defaults to false. Use this to drop the noun set by `integration_type` from the tab title.
145
+
-`redirect_from`: **Note** We aren't using this right now. Defaults to null. Takes an array of URLs from the frontmatter in a file, and generates a "stub" page at each URL. Each stub file redirects to the original file.
146
+
-`seo-changefreq`: default: `weekly `. Use the values [in the sitemap spec](https://www.sitemaps.org/protocol.html#xmlTagDefinitions). - sets the `changefreq` tag in the sitemap.xml generator, which tells search crawlers how often to check back.
147
+
-`seo-priority`: values from `1.0` to `0.1`, default: `0.5 `. Sets the `Priority` tag in the sitemap
148
+
149
+
### Sidenav Icons
150
+
We have two neat icons that you can add to a bottom-level menu item to mark it with an icon. (If it's a folder/directory, the "expand" carat blocks this icon from appearing.)
151
+
152
+
-`menu_icon: read-more` to show a book icon - use this to indicate that there's a lot more in this page than meets the eye
153
+
-`menu_icon: new-tab` to show an "external link" icon. Use this to indicate that the link in the sidenav is taking out outside the segment.com domain (for example to our API references hosted on Postman)
154
+
155
+
156
+
157
+
### Syntax highlighting
158
+
159
+
We're using Rouge, set in the `_config.yml`. It's now default for Jekyll 3 and later, so 🎉.
160
+
A list of the cues Rouge accepts can be found [here](https://github.com/rouge-ruby/rouge/wiki/list-of-supported-languages-and-lexers).
161
+
162
+
### Note Blocks
163
+
We're using [Premonition](https://github.com/lazee/premonition) for our Note blocks. This is stock right now, with four styles: `note`, `info`, `success`, `warning`, and `error`.
164
+
165
+
You'd write a block like this:
166
+
```md
167
+
> warning "I am a warning"
168
+
> The body of the warning goes here. Premonition allows you to write any `Markdown` inside the block.
169
+
```
170
+
171
+
Notes *must* include a `[]` in the heading/title, even if it's empty.
172
+
You can see how to write them in the `styleguide.md`, and see how they render at [https://segment.build/docs/styleguide](https://segment.build/docs/styleguide)
173
+
174
+
175
+
22
176
## Makefile commands
23
177
178
+
-`dev`: runs `jekyll serve` locally with incremental builds. Useful when updating CSS, JS, or content and you don't want to rebuild everytime.
24
179
-`build`: Builds the site docs. Used by CI to publish the docs to staging and production
25
180
-`catalog`: Pulls in the latest catalog data from the Platform API and saves it in the respective data files. Requires an API key to be passed in env via PLATFORM_API_TOKEN
26
181
-`sidenav`: Builds the side navs for 'main', 'legal', 'api', 'partners' and stores the output in `/src/_data/sidenav-auto/`. This output isn't used for the actual build.
27
182
-`typewriter`: pulls in the current state of the Docs tracking plan for implementing Segment tracking
28
-
-`seed`: copies all example data files out of the `_templates` directory and puts them in the `_data` directory. Useful if you don't have a way to setup an API key.
183
+
-`seed`: copies all example data files out of the `_templates` directory and puts them in the `_data` directory. Useful if you don't have a way to set up an API key.
29
184
-`clean`: removes all build artifacts
30
185
-`clean-deps`: removes all downloaded `gems` and `node_modules`
31
186
-`deps`: installs the required `gems` and `node_modules`
32
-
-`dev`: runs `jekyll serve` locally with incremental builds. Useful when updating CSS, JS, or content and you don't want to rebuild everytime.
187
+
33
188
34
189
- docker-build: runs `make build` on a docker host.
35
190
- docker-dev: runs `make dev` on a docker host.
36
191
37
-
# Layouts
192
+
193
+
## Troubleshooting Paper Exports
194
+
195
+
Many of these docs were exported from Paper, which means that they'll have some quirks to sort out.
196
+
197
+
### Endumben-ing
198
+
Paper uses smart-quotes and smart apostrophes, which often can break syntax-sensitive formatting. You can replace them with "dumb" or straight quotes. The characters you're going to want to look for are...
199
+
200
+
’ ‘ “ ” If you "change all" in Atom, you'll remove these examples so please revert changes to this file. ;)
201
+
202
+
Note that these won't always render in Github, so you'll have to make this change using Atom or another text editor.
203
+
204
+
If the examples get removed you can also type these on a Mac by typing
205
+
- Option + [
206
+
- Option + Shift + [
207
+
- Option + ]
208
+
- Option + Shift + ]
209
+
210
+
### Headings vs Titles
211
+
212
+
Our titles are our H1s, so you can remove a top-line H1 if if shows up, and demote all following ones. (This assumes you're using heading formats semantically and not just for formatting. :P )
213
+
214
+
### Image captions
215
+
216
+
What Paper uses as the "caption" is actually what's specified as the "alt text", meaning what a screen-reader would vocalize. It ends up inside the "image" declaration tags.
217
+
218
+
```md
219
+
220
+
```
221
+
### Code-block cleanup
222
+
223
+
By default, Paper uses an old style of markdown that allows you to start a code block by indenting the block. This is rendered okay on our end, but can screw up your code's indentation.
224
+
225
+
Instead, de-indent your code (shift-tab), and add a code-fence of three backticks at the top and bottom.
226
+
227
+
If you know what language it's in, you can also add a "cue" to the first codeblock, which improves how the syntax highlighter renders it (assuming it knows how to format that specific language).
228
+
229
+
230
+
## Developer information
231
+
232
+
233
+
### Layouts
38
234
`default.html` is the container through which all the individual other layouts (currently one, `page.html`) are built to have the right title, seo, etc.
39
235
40
-
# Platform Config API + Catalog
236
+
###Platform Config API + Catalog
41
237
42
-
### Data Source
238
+
####Data Source
43
239
The Segment Config API is currently providing the data for the Source and Destination catalog pages. This happens at build time and the results are stored in the respective `_data/catalog` yml files.
44
240
45
241
For local development, you can always run `make seed` to use the example files if you don't want to mess with interacting with the Platform API.
46
242
47
-
### API Key
243
+
####API Key
48
244
The Platform API needs an API key to pull in the _latest_ catalog data and currently looks for one in the environment variable `PLATFORM_API_TOKEN`. This value is stored in a special file named `.env` that the appropriate scripts reference. You can what this file looks like by looking at `.env.example`
49
245
50
246
If you want to interact with the Platform API, locally, first make sure you have run `make env`. This will create the appropriate `.env` file for you to work with
@@ -53,7 +249,7 @@ If you want to interact with the Platform API, locally, first make sure you have
53
249
54
250
Once your local environment is configured, you then have two options to pull Platform API data: You can use the token in [`chamber`](https://github.com/segmentio/chamber) or you can create your own token. The one in chamber is also used by CircleCI when the docs are built + deployed.
55
251
56
-
#### Chamber
252
+
#####Chamber
57
253
58
254
If you installed and have access to `chamber`, run the following command:
59
255
@@ -83,52 +279,22 @@ $ make catalog
83
279
"Done."
84
280
```
85
281
86
-
#### Bring your own token
282
+
#####Bring your own token
87
283
88
284
You create your own token via the Access Management Page. Feel free to use [`segment-engineering`](https://app.segment.com/segment-engineering/settings/access-management) or [`segment_prod`](https://app.segment.com/segment_prod/settings/access-management). Once you have the token, set the value in the `.env` file.
89
285
90
286
91
-
### Catalog Data + Doc Links
287
+
####Catalog Data + Doc Links
92
288
By default, the links on the catalog page and respective sidenavs will attempt to automagically set hyperlinks, for actual doc file, at the path `connections/:type/:slug`. However, given the transitory state of Docs V2, these links might 404 since the respective doc might be in a different directory.
93
289
94
-
### Object Sources and Warehouses
290
+
####Object Sources and Warehouses
95
291
These two catalogs are hardcoded in the `_data` directory since the Config API does not expose these resources.
96
292
97
-
# Sidenav
293
+
###Sidenav
98
294
The sidenav is managed by the files in `_data/sidenav/`. Depending on what section we are in determines the file used. We currently support up to 2 levels deep on a sidenav.
99
295
100
-
# Breadcrumb
296
+
###Breadcrumb
101
297
The current breadcrumb is currently determined based on the `page.path` and the current page's `title` front-matter attribute.
102
298
103
-
# Searching
104
-
299
+
### Searching
105
300
Swiftype is set up as a script in `_layouts/default.html`
106
-
107
-
108
-
# Syntax highlighting
109
-
110
-
We're using Rouge, set in the `_config.yml`. It's now default for Jekyll 3 and later, so 🎉.
111
-
A list of the cues Rouge accepts can be found [here](https://github.com/rouge-ruby/rouge/wiki/list-of-supported-languages-and-lexers).
112
-
113
-
# Note Blocks
114
-
We're using [Premonition](https://github.com/lazee/premonition) for our Note blocks. This is stock right now, with four styles: `note`, `info`, `warning`, and `error`. We might build more later.
115
-
116
-
You'd write a block like this:
117
-
```md
118
-
> warning "I am a warning"
119
-
> The body of the warning goes here. Premonition allows you to write any `Markdown` inside the block.
120
-
```
121
-
122
-
123
-
# Frontmatter
124
-
125
-
-`beta`: default false. When true, show an "in beta" warning in the page layout (see the warning in `_includes/content/beta.md`)
126
-
-`description`: takes a string. Adds the text here to the meta "description" tag used for SEO purposes
127
-
-`feedback`: defaults to true. When false, hide the feedback footer. Good for legal and landing pages,
128
-
-`hidden`: omits the file from the `sitemap.xml` and adds a `<meta name="robots" content="noindex" />` to the top of the generated HTML file. TODO: it should probably also omit the item from the navbar generator script 🤔
129
-
-`hide_toc`: hides the right-nav TOC that's generated from H2s
130
-
-`integration_type`: This is set on two paths in the `_config.yml` to add a noun (Source or Destination) to the end of the title, and the end of the title tag in the html layout.
131
-
-`landing`: defaults to false. Use this to drop the noun set by `integration_type` from the title and heading.
132
-
-`redirect_from`: defaults to none. Takes an array of URLs from the frontmatter in a file, and generates a "stub" page at each URL. Each stub file redirects to the original file.
133
-
-`seo-changefreq`: default: `weekly `. Use the values [in the sitemap spec](https://www.sitemaps.org/protocol.html#xmlTagDefinitions). - sets the `changefreq` tag in the sitemap.xml generator, which tells search crawlers how often to check back.
134
-
-`seo-priority`: values from `1.0` to `0.1`, default: `0.5 `. Sets the `Priority` tag in the sitemap
0 commit comments