|
| 1 | +# Contributing to Segment Docs |
| 2 | + |
| 3 | +## Getting Started |
| 4 | + |
| 5 | +Before you begin: |
| 6 | + |
| 7 | +- This site is powered by [Jekyll](https://www.jekyllrb.com). |
| 8 | +- Please familiarize yourself with the licensing agreement. |
| 9 | +- Browse existing issues to see if your issue has been raised already. |
| 10 | + |
| 11 | +## Use the contribution links from any docs page |
| 12 | + |
| 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 | + |
| 15 | +## Want to go deeper? Clone the repository |
| 16 | + |
| 17 | +You can clone this repository to your local machine to make larger changes. Examples of larger changes include: |
| 18 | +- editing more than one file at a time |
| 19 | +- adding or updating images |
| 20 | +- updating navigation items |
| 21 | + |
| 22 | +In this scenario, you'll clone the repository locally, make your changes, and submit a pull request to have them reviewed and merged back into the site. |
| 23 | + |
| 24 | +## Site structure |
| 25 | + |
| 26 | +As mentioned, the Segment docs site is powered by Jekyll, with a few customizations and enhancements. Generally speaking, everything you'll need to edit is located in the `_src/` directory. This directory contains the data files, layouts, sass, and markdown source files that combine to make a live, working website. |
| 27 | + |
| 28 | +Within the `/src/` path, anything that starts with an underscore (like `_data` or `_includes`) is a utility directory, and Jekyll won't render it as a webpage path at build time. (In fact, any files where the name starts with an underscore are dropped from the build.) |
| 29 | + |
| 30 | +### Underscore files |
| 31 | + |
| 32 | +Anything that starts with an `_` is a utility directory of some sort (and Jekyll will skip/not render any file that starts with a `_`). |
| 33 | + |
| 34 | +The most interesting ones are: |
| 35 | +- `/src/_includes/content/` This is where all the includes or "partials" - the reusable content - are stored. |
| 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. |
| 38 | + |
| 39 | + |
| 40 | +### Images |
| 41 | + |
| 42 | +**Save all images locally! No linking to 3rd 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. |
| 43 | + |
| 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. |
| 45 | + |
| 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. |
| 47 | + |
| 48 | +A few possibilities/suggestions: |
| 49 | + |
| 50 | +- **Add a prefix of what file the image appears in**. This is helpful if you have images for multiple pages in the same `images` directory, but breaks down a bit if you reuse images across multiple pages. |
| 51 | +- **Give a prefix of the application the screenshot shows**. For example `atom-new-file.png`, `atom-commit-changes.png` etc), |
| 52 | +- **Name images to describe a process flow**. For example `checkout-1-add-to-cart.png`, `checkout-2-est-shipping.png` and so on. |
| 53 | + |
| 54 | + |
| 55 | +### Content structure |
| 56 | + |
| 57 | +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). |
| 58 | + |
| 59 | +For the Connections product, the section is divided into the Spec, then Sources, Destinations, and Storage Destinations (formerly called "Warehouses"), with general accessory topics at the folder root. (More specific accessory topics are in each sub directory.) |
| 60 | + |
| 61 | +Each also contains a `catalog` directory, which contains all the directories with information about specific integrations. The top-level of this `catalog` 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, either in `destinations.yml`, `sources.yml`, or `warehouses.yml`. |
| 62 | + |
| 63 | + |
| 64 | +### Programmatic content |
| 65 | + |
| 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. |
| 67 | + |
| 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. |
| 69 | + |
| 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`. |
| 71 | + |
| 72 | +Destination pages include the `destination-dossier.html` and `destination_footer.md` content, which use Liquid scripting and pulls from the catalog metadata. |
| 73 | + |
| 74 | +Sources pages check if the source is a cloud-app, then include information about if the source is an object or event source, based on the `type` data from the ConfigAPI. |
| 75 | + |
| 76 | +## Edit pages |
| 77 | + |
| 78 | +Content with in each `.md` file is markdown. For information about styling, and available extensions, see `_src/utils/formatguide.md` or the live version [here](https://segment.com/docs/utils/formatguide). |
| 79 | + |
| 80 | +### Frontmatter |
| 81 | + |
| 82 | +Each Markdown file in the docs can have "frontmatter" associated with it at the top of the file. These are considered by Jekyll to be "properties" of a page, generally control how the HTML page is built or rendered. |
| 83 | + |
| 84 | +Frontmatter in a file will look something like this: |
| 85 | + |
| 86 | +```md |
| 87 | +--- |
| 88 | +title: Analytics.js Library |
| 89 | +hide-feedback: false |
| 90 | +--- |
| 91 | +``` |
| 92 | + |
| 93 | +Each piece of frontmatter does something special! |
| 94 | + |
| 95 | +#### Content-related frontmatter |
| 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 frontmatter 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. |
| 98 | +- `hide-dossier`: defaults to false. When true, hides the "quick info" box at the top of a destination page. |
| 99 | +- `hide-boilerplate`: defaults to false. When true, none of the content from `destination-footer.md` is appended to the destination page. |
| 100 | +- `hide-cmodes`: defaults to false. A renaming of "rewrite" for more clarity, hides the connection modes table in the boilerplate. |
| 101 | +- `hide-personas-partial`: defaults to false. When true, hides the section of content from `destination-footer.md` that talks about being able to receive personas data. |
| 102 | +- `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. |
| 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. |
| 104 | + |
| 105 | +#### Utility frontmatter |
| 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. |
| 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. |
| 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. |
| 110 | +- `hide_toc`: hides the right-nav TOC that's generated from H2s. Also good for landing pages. |
| 111 | +- `landing`: defaults to false. Use this to drop the noun set by `integration_type` from the tab title. |
| 112 | +- `redirect_from`: Defaults to null. Takes an array of URLs from the frontmatter 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. |
| 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. |
| 114 | +- `seo-priority`: values from `1.0` to `0.1`, default: `0.5 `. Sets the `Priority` tag in the sitemap |
0 commit comments