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
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+13-22Lines changed: 13 additions & 22 deletions
Original file line number
Diff line number
Diff line change
@@ -12,24 +12,14 @@ Before you begin:
12
12
13
13
Not all pages have a 1-1 mapping with their location within the repository. This can make browsing and locating the file you're trying to reference a challenge. As you browse [segment.com/docs](https://segment.com/docs), you'll notice two links in the right sidebar, at the top of the page. Click **Edit this page** to open the page in the GitHub editor. Or, click **Request docs change** to create a new issue that references the page.
14
14
15
-
This is the best path to update a single page, or make a small change to a single article.
16
-
17
15
## Want to go deeper? Fork the repository
18
16
19
17
You can fork this repository and clone it to your local machine to make larger changes. Examples of larger changes include:
20
18
- editing more than one file at a time
21
19
- adding or updating images
22
20
- updating navigation items
23
21
24
-
In this scenario, you'll fork the repository, clone it locally, make your changes, and submit a pull request to have them reviewed and merged back into the site. For more information, see the [Dev Guide](devguide.md).
25
-
26
-
## Have your changes reviewed
27
-
28
-
When you update a page on the Segment Docs site, either by the "Edit this page" link, or by forking the repository, your changes will go through the Pull Request process. When you open a Pull Request, you're saying "Hey Segment Docs team, I'd like to update the site with these updates." When the Pull Request is opened, it is assigned for review to the docs writer who is most active in that area of the documentation. This is maintained in the CODEOWNERS file. If there is no writer assigned to a specific area, your pull request will be randomly assigned to a member of the team.
29
-
30
-
Once you submit, the reviewer may have questions about your submission. This conversation will take place with GitHub conversations in the context of the Pull Request.
31
-
32
-
When your Pull Request is approved and merged, it will go live on the site with the teams next deploy (mornings, Pacific time on Tuesdays and Thursdays).
22
+
In this scenario, you'll fork the repository, clone it locally, make your changes, and submit a pull request to have them reviewed and merged back into the site.
33
23
34
24
## Site structure
35
25
@@ -43,17 +33,17 @@ Anything that starts with an `_` is a utility directory of some sort (and Jekyll
43
33
44
34
The most interesting ones are:
45
35
-`/src/_includes/content/` This is where all the includes or "partials" - the reusable content - are stored.
46
-
-`/src/_data/catalog/` This is where data pulled from the Public API is stored, in structured `yml` files that are used by the build.
47
-
-`/src/_data/sidenav/` This is where the navigation structures are. (Several sections in the doc have their own left-nav, making them "microsites".) They're just YML files that manually updated.
36
+
-`/src/_data/catalog/` This is where we keep the data we've pulled from the ConfigAPI in structured `yml` files that are used by the build.
37
+
-`/src/_data/sidenav/` This is where the navigation structures are. (Several sections in the doc have their own left-nav, making them "microsites".) They're just YML files that we manually update so we have maximum control over what's shown and what's not.
48
38
49
39
50
40
### Images
51
41
52
-
**Save all images locally! No linking to third-party hosted images!** Images are published to the Netlify CDN from the build step.
42
+
**Save all images locally! No linking to third-party hosted images!** Images are published to our CDN from the build step, and this means they won't go missing if the hosting service dujour goes out of business.
53
43
54
-
There are no _enforced_ naming conventions. Files that start with an underscore are ignored by Jekyll.
44
+
There are no _enforced_ naming conventions at this time. Files that start with an underscore are ignored by Jekyll. Anything you see with `asset` was dowloaded by a script to migrate it out of Contents.io.
55
45
56
-
It's a good practice to name images with a description that helps you (& other docs maintainers) figure out where they should go within a page, or within a larger folder of images.
46
+
In general, it's a good practice to name images with a description that helps you (& other docs maintainers) figure out where they should go within a page, or within a larger folder of images.
57
47
58
48
A few possibilities/suggestions:
59
49
@@ -73,9 +63,9 @@ Each also contains a `catalog` directory, which contains all the directories wit
73
63
74
64
### Programmatic content
75
65
76
-
Programmatic content is sections of documentation that are built conditionally, or using public information from the Public API.
66
+
Programmatic content is sections of documentation that are built conditionally, or using public information from our Config API. This is *awesome* and like the holy grail of docs systems.
77
67
78
-
Programmatic content is built using information in the files in `/src/_data/catalog/`. These files (with the exception of `warehouses.yml`) are built by the `make catalog` command, which contacts the public Public API, gets a list of all the available integrations using the Catalog endpoint, and then parses them into static `.yml` files.
68
+
Programmatic content is built using information in the files in `/src/_data/catalog/`. These files (with the exception of `warehouses.yml`) are built by the `make catalog` command, which contacts our public ConfigAPI, gets a list of all the available integrations using the Catalog API, and then parses them into static `.yml` files.
79
69
80
70
Most of the programmatic content is built into the `_layouts` templates that each page uses. Sources, Destinations, and Warehouses use the `integration.html` template, which uses some Liquid logic, and calls an `include` depending on the integration type. Most of logic for the actual content must live in the include file itself, however logic controlling *if* the include is built can live in the `layout`.
81
71
@@ -104,6 +94,7 @@ Front matter variables have unique functions, including the following:
104
94
105
95
#### Content-related front matter
106
96
-`beta`: default false. When true, show an "in beta" warning in the page layout (see the warning in `_includes/content/beta-note.md`)
97
+
-`rewrite`: defaults to false. This is a legacy front matter flag that comes from the old `site-docs` repo, and which labels any destination that was rewritten in ~2018 to a standardized template. It disables the duplicate "connection modes" table that would otherwise show up in the boilerplate content at the end of the page.
107
98
-`hide-dossier`: defaults to false. When true, hides the "quick info" box at the top of a destination page.
108
99
-`hide-boilerplate`: defaults to false. When true, none of the content from `destination-footer.md` is appended to the destination page.
109
100
-`hide-cmodes`: defaults to false. A renaming of "rewrite" for more clarity, hides the connection modes table in the boilerplate.
@@ -112,12 +103,12 @@ Front matter variables have unique functions, including the following:
112
103
-`source-type`: These are only used to supplement when a Cloud App in the sources path doesn't appear in the Config API list, and needs its type explicitly set. It runs some logic in the `cloud-app-note.md` to explain which cloud-apps are object vs event sources.
113
104
114
105
#### Utility front matter
115
-
-`published`: defaults to true. Set this to "false" to prevent Jekyll from rendering an HTML page for this file. Good for when you're working on something in the repository but aren't ready to release it yet, and don't want to use a Draft PR.
106
+
-`published`: defaults to true. Set this to "false" to prevent Jekyll from rendering an HTML page for this file. Good for when you're working on something in the repo but aren't ready to release it yet, and don't want to use a Draft PR.
116
107
-`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.
117
-
-`hide-sidebar`: defaults to false. When true, hide the entire right-nav sidebar. Use with `hide-feedback` if you want to disable *all* feedback opportunities.
118
-
-`hide-feedback`: defaults to false. When true, hide the feedback in both nav and footer. Good for landing pages.
108
+
-`hide-sidebar`: defaults to false. When true, hide the entire right-nav sidebar. Use with `hide-feedback` if you want to disable *all* feedback affordances.
109
+
-`hide-feedback`: defaults to false. When true, hide the feedback in both rnav and footer. Good for landing pages.
119
110
-`hide_toc`: hides the right-nav TOC that's generated from H2s. Also good for landing pages.
120
111
-`landing`: defaults to false. Use this to drop the noun set by `integration_type` from the tab title.
121
-
-`redirect_from`: Defaults to null. Takes an array of URLs from the front matter in a file, and generates a "stub" page at each URL at build-time. Each stub file redirects to the original file. Use the path from the root of the content directory, for example `/connections/destinations/catalog/` rather than `/docs/connections/destinations/catalog/`.
112
+
-`redirect_from`: Defaults to null. Takes an array of URLs from the front matter in a file, and generates a "stub" page at each URL at build-time. Each stub file redirects to the original file. Use the path from the root of the content directory, for example `/connections/destinations/catalog/` rather than `/docs/connections/destinations/catalog/`.**Note** We are mostly using NGINX redirects for SEO purposes. Approximately quarterly, we'll collect these and add them to NGINX.
122
113
-`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.
123
114
-`seo-priority`: values from `1.0` to `0.1`, default: `0.5 `. Sets the `Priority` tag in the sitemap
0 commit comments