Here's what's here!
+We are now splitting out the Readme into three parts:
+- [Contributor Guide](contributors.md)
+- [Style Guide](styleguide.md)
+- [Technical Details](devguide.md)
+
- [Contributing to the Segment Docs](#contributing-to-the-segment-docs)
+- [Quickstart](#quickstart)
- [Most frequently asked question: Do I need a review?](#most-frequently-asked-question-do-i-need-a-review)
- [How to docs (The Docs Process)](#how-to-docs-the-docs-process)
-- [Repo structure](#repo-structure)
+- [How the docs build works](#how-the-docs-build-works)
- [Formatting and Prettifying](#formatting-and-prettifying)
+- [Repo structure](#repo-structure)
- [Frontmatter](#frontmatter)
+- [Navigation](#navigation)
- [Makefile commands](#makefile-commands)
-- [Troubleshooting Paper Exports](#troubleshooting-paper-exports)
-- [Developer information](#developer-information)
+
+
## Contributing to the Segment Docs
-### Quickstart (local development with docker)
-You will need to have Docker installed https://docs.docker.com/install/
+## Quickstart
-* If using Linux, run `docker-compose up`
-* Visit http://localhost:4000/docs/
+Git clone this repo, navigate to it in Terminal, run `make env`.
+This will install everything you need to edit the docs, and run the docs build locally.
-### Local development with `ruby` and `node`, without platform-api
+Edit the content files, check them in on a new branch, PR to the main repo, and when your PR is merged to `master`, the site automatically rebuilds.
-If using OSX:
- * Install command line tools, `xcode-select --install`
- * Install `Ruby` >= 2.3.0 https://www.ruby-lang.org/en/documentation/installation/
- * Ensure you're running `RubyGems` >= 2.5.0 by running `gem update --system` followed by `gem --version`
- * Install `Bundler 2` with `gem install bundler`
- * Install `Node` https://nodejs.org/en/download/
- * Install `Yarn` https://yarnpkg.com/en/docs/install
- * Run server, `make dev`
- * Visit http://localhost:4000/docs/
+For more details, see the [Contributor Guide](contributors.md)!
### JUST Editing content?
-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.
-
-#### Recommended editors
-
-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.
- - language-markdown
- - markdown-preview
- - markdown-table-editor
- - markdown-toc
-
-Some folks use Sublime. (Please add your tips and comments here if you do!)
+You can make a limited range of edits [from the Github site](contributors.md/#contribute-from-the-github-web-ui)! Hooray! But this system works best if you clone it locally so you can run test builds.
+See the [Contributor Guide](contributors.md) for more info.
## Most frequently asked question: Do I need a review?
@@ -74,7 +64,6 @@ The docs repo works on the honor system right now. The only rule is you can't me
2. Create a new branch and make your changes.
- Change the content in the files.
- If needed, update the appropriate file in the `src/_data/sidenav/` to reflect your changes.
- - 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.
3. Commit your changes.
3. Push the branch to `segment-docs` and make a PR to master.
- 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.)
@@ -90,72 +79,79 @@ The docs repo works on the honor system right now. The only rule is you can't me
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.
+
+## How the docs build works
+
+The actual content that you see on segment.com/docs lives in this repository, most of it in the `/src/` folder and its subdirectories. Everything outside of that folder is related to the build, styling, tracking, and process for this repo.
+
+These files are built by Jekyll, our static-site builder program, into a full site of static HTML pages. We do not have any interactive or adaptive content on the site at this time.
+
+When you run `make dev` (or `make docs`) on your laptop, Jekyll runs the same program that it uses to publish the public site content. It builds the page templates, then builds an HTML page for each markdown file (or html file) in the `src` path[**](#underscore-files). Some of these files include Liquid script, which allows them to load reusable content ("includes"), render fancy HTML styling, and run simple code processes to build programmatic content. As long as the Jekyll process is running on your laptop, you can edit the content of a page in markdown and save it, and Jekyll will detect the change and rebuild that page so you can view it locally. However, this doesn't work for the page layouts (and a few other things), which are assumed to be static at build time.
+
+When you merge a PR to master, our build system runs the Jekyll program, and automatically publishes the rebuilt HTML files to our web server. (Which is why we *require* that the Buildkite build passes before you merge!)
+
+## Formatting and Prettifying
+Some important tips are in the [styleguide](styleguide.md). We also have a (rendering)[Formatting guide](/src/utils/formatguide.md) available so you can see how different formatting looks when rendered.
+
## Repo structure
All of the content files live in the `/src/` directory. Everything outside of this is related to the build.
-### Utility files
+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.)
+
+### Underscore files
+
Anything that starts with an `_` is a utility directory of some sort (and Jekyll will skip/not render any file that starts with a `_`).
The most interesting ones are:
-- `/src/_includes/content/` This is where all the partials - the reusable content - are stored.
-- `/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.
-- `/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.
+- `/src/_includes/content/` This is where all the includes or "partials" - the reusable content - are stored.
+- `/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.
+- `/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.
-### Content files
-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).
-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.
+### Images
-### Intelligent content
-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.
+**All images should be saved locally! No linking to 3rd party-hosted images!** Images are published to our CDN from the build step.
+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 save it from Contents.io. :)
-## Formatting and Prettifying
-Some important tips! We also have a (rendering)[Formatting guide](/src/utils/formatguide.md) available so you can see how different formatting looks when rendered.
+In general, it's a good practice to name images with a description that helps you figure out where they should go within a page, or within a larger folder of images. Naming with a prefix of what application the screenshot contains can be helpful (for example `atom-new-file.png`, `atom-commit-changes.png` etc), or you can name images to describe a process flow (for example `checkout-1-add-to-cart.png`, `checkout-2-est-shipping.png` and so on).
-### Diagrams
+### Diagram Library
We have a diagram library in sketch, which you can use to build pretty, on-brand architecture diagrams, etc. There's a [readme file in that directory](diagram-library/readme.md) with instructions on how to use it.
-### Adding Images
+### Content structure
-**All images should be saved locally! No linking to 3rd party-hosted images!**
+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).
-As CDN hosting is from the publish side, we shouldn't be worrying about that at the file level.
+For the Connections product, the section is divided into the Spec, then 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.
-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.
-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 save it from Contents.io. :)
+### Programmatic content
-In general, it's a good practice to name images with a description that helps you figure out where they should go within a page, or within a larger folder of images. Naming with a prefix of what application the screenshot contains can be helpful (for example `atom-new-file.png`, `atom-commit-changes.png` etc), or you can name images to describe a process flow (for example `checkout-1-add-to-cart.png`, `checkout-2-est-shipping.png` and so on).
+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.
-### Adding links
+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.
-Use the standard markdown format for links (ex: `[text](https://example.com)`).
-To make a link open in a new tab append `[text](https://example.com){:target="_blank"}` to the end.
+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`.
-### Escaping code snippets
+Destination pages include the `integration_foot.md` content which uses Liquid scripting and pulls from the catalog metadata.
-Certain code syntax will be interpreted by Jekyll/Liquid as site code. If you're having trouble showing code snippets in the docs, you can wrap the snippet in a `{% raw %}` tag. In the example below, the curly brackets would not render in the docs. The raw tags ensure the code renders properly.
+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.
-```
-{% raw %}
-To pass source name in the slack message, format it like so: `{{properties.sourceName}}`
-{% endraw %}
-```
## Frontmatter
-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".
+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.
-It'll look something like this:
+Frontmatter in a file will look something like this:
-```text
- ---
- title: Analytics.js Library
- hide-feedback: false
- ---
+```md
+---
+title: Analytics.js Library
+hide-feedback: false
+---
```
Each piece of frontmatter does something special!
@@ -172,10 +168,14 @@ Each piece of frontmatter does something special!
- `hide-feedback`: defaults to false. When true, hide the feedback footer. Good for legal and landing pages.
- `hide_toc`: hides the right-nav TOC that's generated from H2s
- `landing`: defaults to false. Use this to drop the noun set by `integration_type` from the tab title.
-- `redirect_from`: **Note** We are mostly using NGINX redirects. 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.
+- `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. **Note** We are mostly using NGINX redirects for SEO purposes. Approximately quarterly, we'll collect these and add them to NGINX.
- `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.
- `seo-priority`: values from `1.0` to `0.1`, default: `0.5 `. Sets the `Priority` tag in the sitemap
+## Navigation
+
+The navigation is built from a static yml file, which allows us maximum control over what appears there and when.
+
### Sidenav Icons
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.)
@@ -183,30 +183,10 @@ We have two neat icons that you can add to a bottom-level menu item to mark it w
- `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)
-### Syntax highlighting
-
-We're using Rouge, set in the `_config.yml`. It's now default for Jekyll 3 and later, so 🎉.
-A list of the cues Rouge accepts can be found [here](https://github.com/rouge-ruby/rouge/wiki/list-of-supported-languages-and-lexers).
-
-### Note Blocks
-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`.
-
-You'd write a block like this:
-```md
-> warning "I am a warning"
-> The body of the warning goes here. Premonition allows you to write any `Markdown` inside the block.
-```
-
-Notes *must* include a `[]` in the heading/title, even if it's empty.
-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)
-
-### Redirect to a workspace
-Occasionally, you'll want to deep-link into the Segment app to link a reader to a specific page or screen. Previously we'd throw them an URL and say "replace {MY SLUG} with your actual workspace slug", but now you can use the slug of `goto-my-workspace` and the Segment app will redirect them.
-https://app.segment.com/goto-my-workspace/destinations/catalog
-
## Makefile commands
- `dev`: runs `jekyll serve` locally with incremental builds. Useful when updating CSS, JS, or content and you don't want to rebuild everytime.
+- `docs`: same as `make dev`, but for Laura's convenience.
- `build`: Builds the site docs. Used by CI to publish the docs to staging and production
- `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. [Instructions here](#bring-your-own-token).
- `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.
@@ -219,141 +199,3 @@ https://app.segment.com/goto-my-workspace/destinations/catalog
- docker-build: runs `make build` on a docker host.
- docker-dev: runs `make dev` on a docker host.
-
-
-## Troubleshooting Paper Exports
-
-Many of these docs were exported from Paper, which means that they'll have some quirks to sort out.
-
-### Endumben-ing
-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...
-
-’ ‘ “ ” If you "change all" in Atom, you'll remove these examples so please revert changes to this file. ;)
-
-Note that these won't always render in Github, so you'll have to make this change using Atom or another text editor.
-
-If the examples get removed you can also type these on a Mac by typing
-- Option + [
-- Option + Shift + [
-- Option + ]
-- Option + Shift + ]
-
-### Headings vs Titles
-
-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 )
-
-### Image captions
-
-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.
-
-```md
-
- ```
-### Code-block cleanup
-
-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.
-
-Instead, de-indent your code (shift-tab), and add a code-fence of three backticks at the top and bottom.
-
-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).
-
-
-## Developer information
-
-
-### Layouts
-`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.
-
-### Platform Config API + Catalog
-
-#### Data Source
-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.
-
-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.
-
-#### API Key
-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`
-
-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
-
-**NOTE: Never check-in `.env` or remove it from `.gitignore`.**
-
-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.
-
-##### Chamber
-
-If you installed and have access to `chamber`, run the following command:
-
-```bash
-$ aws-okta exec prod-privileged -- chamber read segment-docs platform_api_key
-```
-
-or for staging...
-
-```bash
-$ aws-okta exec stage-privileged -- chamber read segment-docs platform_api_key
-```
-
-You should get something like this as the output of the command.
-```bash
-Key Value Version LastModified User
-platform_api_key [REDACTED FOR DOCS] 2 08-05 10:24:55 arn:aws:sts::752180062774:assumed-role/production-write/bryan.mikaelian@segment.com
-```
-
-Edit the `.env` file (generated from `make env`) and replace the environment variable with the token above. `make catalog` should then work and you should see some output like this:
-
-```bash
-$ make catalog
-"Saving catalogs from Platform API..."
-"Finished Destinations."
-"Finished Sources."
-"Done."
-```
-
-##### Bring your own token
-
-You create your own token in the Segment App. You can use your own personal workspace, or if you have access to them, use [`segment-engineering`](https://app.segment.com/segment-engineering/settings/access-management) or [`segment_prod`](https://app.segment.com/segment_prod/settings/access-management). Go to **Settings > Access Management > Tokens**.
-Any type of token will work, but you might want to limit it to a read-only token. Make sure you label it so folks know what it's for!
-
-Once you make a new token, paste the token value in the `.env` file like so:
-
-```text
-PLATFORM_API_TOKEN=(token value here)
-```
-You can now run `make catalog`!
-
-
-#### Catalog Data + Doc Links
-By default, the links on the catalog page and respective sidenavs 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.
-
-#### Object Sources and Warehouses
-These two catalogs are hardcoded in the `_data` directory since the Config API does not expose these resources.
-
-### Sidenav
-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.
-
-### Breadcrumb
-The current breadcrumb is currently determined based on the `page.path` and the current page's `title` front-matter attribute.
-
-### Searching
-Swiftype is set up as a script in `_layouts/default.html`
-
-
-## Testing
-
-### Build Testing
-Currently the only automatic testing we perform is linting on the configuration yaml files to ensure proper the project will build.
-
-TODO: define rules for markdown linting and clean up linting errors
-`npx remark ./src --use preset-lint-markdown-style-guide`
-
-### Manual Testing
-There is as also some manual testing scripts that can be run to validate the build.
-
-1. `tests/redirects/redirects_bash`: used for validating a list of paths that we have nginx redirects for
-
-2. `tests/externalLinks/linkTester_bash`: used to validate that external links referenced in docs point to a validate endpoint
-
-3. `tests/imageSizes/getImageSizes.js`: used to get the 10 largest images in the repo.
-
-4. `npx mdspell 'src/**/*.md' -r --en-us`: used to validate spelling in docs, needs to be configured to add Segment terms.
diff --git a/contributors.md b/contributors.md
new file mode 100644
index 0000000000..409170b2e2
--- /dev/null
+++ b/contributors.md
@@ -0,0 +1,195 @@
+# Segment Docs Contributors Guide
+
+Thanks for helpin' out! We really appreciate it.
+
+
+
+
+There are three ways to contribute.
+- EASY: [Contribute from the Github web UI](#contribute-from-the-github-web-ui) - only use this when making small edits to existing text files
+- INTERMEDIATE: [Contribute using Git and Atom](#contribute-using-git-and-atom) - use this for everything else
+- ADVANCED: [Contribute using Git](#contribute-using-git-native-commands) - if you're a git nerd, you can use this method
+
+If you're changing how the docs render, adding files or changing images, you should use the intermediate or advanced options.
+
+This guide also contains a bunch of [useful formatting tips and tricks](#tips-and-tricks), plus instructions on how to [set up to run the docs locally](#set-up-on-mac-using-the-env-script), and how to [refresh the docs-catalog files](#refresh-the-segment-catalog).
+
+
+## Contribute from the Github web UI
+
+> **Use this method when making small edits to an existing file only.**
+> Don’t use this when:
+> - Editing more than one file at a time,
+> - Adding or removing image files
+> - Making edits that change how the docs or docs navigation works.
+>
+> In those cases, set up to [contribute using Atom], and run the docs locally to confirm that your changes work and render as expected.
+
+1. Go to https://github.com/segmentio/segment-docs/tree/master/src, find the file you want to edit, and click the Pencil icon - “Edit this file”
+ 
+2. Make your changes.
+3. Scroll all the way to the bottom and make a note about your change.
+ 
+4. Click **Propose file change**.
+5. On the next screen, add a reviewer or two.
+ These should be folks who know enough about the content change to give it a thumbs up. If you don't know who that is, you can also tag @sanscontext for a docs-team review.
+6. Once someone has reviewed and approved the change, merge the change.
+7. Delete the branch once the change has been merged!
+
+**If changes are needed on your Github PR**: You (or they) can add Github "suggestions", which you can merge into your PR one by one. If there are many updates, you might need to check out your branch using the Atom and Git process below to make the changes in a single commit.
+
+## Contribute using Git and Atom
+
+If you are adding files, changing images, making large or long-running changes to some docs, or changing how the docs are ordered or rendered, you should use Git. If you're not a git-native, your best bet is to use Atom, the Github-created open-source editor. This requires a bit of setup the first time, but we'll put that in a separate section!
+
+> ℹ️ **Before you begin**: Make sure you've installed Atom. You can either install as part of running the `make env` command [described below](), or by > following the [Atom installation instructions](https://flight-manual.atom.io/getting-started/sections/installing-atom/).
+
+1. Open Atom, and make sure the Git tool panel is open.
+ (Press `Ctrl + Shift + 9` to open or close it, or find it in the **Packages** menu in Atom.)
+2. Switch to the `master` branch, and update/fetch master from within Atom, using the 🔄 Fetch button
+ 
+3. Create a new branch from `master`. This is where you’ll commit your changes.
+ 
+4. Make your changes, and save the files you’ve changed.
+5. Stage changes. This means you mark them as specific files that you want to save and check in.
+6. Add a short commit message, and click **Commit to (branchname)**. This adds a save point to your branch.
+ 
+
+7. Click **Publish** (or **Push**).
+
+8. Go to the [Segment-docs repo in Github](https://github.com/segmentio/segment-docs), and create new Pull Request (PR).
+ A pull request is how you ask to add your changes to the public version of the documentation.
+ If you recently pushed a new branch, Github will prompt you to open a PR by clicking the Compare & pull request button.
+ 
+ (If you don’t see this, you can go to **Pull requests** tab, and click **New pull request**, then in the second drop down, find your branch name.)
+9. Open your Pull request.
+ 1. Add a good title that explains what your change does.
+ 2. Fill out the template sections. At minimum you should explain what this change does, but you can also link to Github issues or Jiras, or other conversations about the issue you’re fixing.
+ 
+10. Next, request a review or two. One person should be able to check for typos, the other for technical inaccuracies.
+
+ If you’re making a large change, you should include someone from the Engineering or Product teams.
+ Github will suggest the last few people who edited that file. That’s often a good way to go! If not, you can requesting a review from sanscontext.
+ 
+
+
+
+### Making review edits in a PR
+
+Your reviewers might ask you to make changes to your PR before merging it. You can do this easily in Atom: Just follow steps 4-7 above as needed. (Make the change(s), save the file(s), stage them, write a commit message, and push.) They’ll get added to the changes already in the branch in your Pull Request!
+
+Once your PR has been reviewed, approved, and all the automated tests completed, click **Squash and Merge**, and then **Delete branch** to clean up after yourself!
+
+Back in Atom, you can do a bit of pre-work by selecting the `master` branch and clicking and **Pull**. Now you're ready for the next edits!
+
+
+## Contribute using git native commands
+
+This section is a very sparse outline of a git flow for git-experts and other folks with strong opinions about Atom. ;) It assumes that you have a favorite text editor, git installed, and that you've already set done a `git clone` to create the local segment-docs repo.
+
+1. Change to and update master (`git checkout master && git pull`)
+2. Create a new branch from master (`git checkout -b my_new_branch`)
+3. Make changes, save them.
+4. Stage your changes (`git status` and `git add` the appropriate files)
+5. Commit staged changes to your branch (`git commit`)
+6. Push your branch and changes to the `segment-docs` repo (`git push`, `git push --set-upstream origin`)
+7. Repeat steps 3-6 as needed.
+8. Open a PR by [going to the PRs page](https://github.com/segmentio/segment-docs/pulls), if not prompted, create new by selecting `master` as base, `(your branch name)` as other.
+9. Request a review. The Codeowners should populate this, and if not you can tag @sanscontext.
+10. If changes are requested, repeat steps 3-6 as needed.
+11. Once approved, merge and delete branch, delete branch locally.
+
+
+## Tips and tricks
+
+
+### Adding links that open in a new window
+
+Use the standard markdown format for links (ex: `[text](https://example.com)`).
+To make a link open in a new tab append `[text](https://example.com){:target="_blank"}` to the end.
+
+### Escaping code snippets
+
+Certain code syntax will be interpreted by Jekyll/Liquid as site code. If you're having trouble showing code snippets in the docs, you can wrap the snippet in a `{% raw %}` tag. In the example below, the curly brackets would not render in the docs. The raw tags ensure the code renders properly.
+
+```
+{% raw %}
+To pass source name in the slack message, format it like so: `{{properties.sourceName}}`
+{% endraw %}
+```
+
+
+### Syntax highlighting
+
+We're using Rouge, set in the `_config.yml`. It's now default for Jekyll 3 and later, so 🎉.
+A list of the cues Rouge accepts can be found [here](https://github.com/rouge-ruby/rouge/wiki/list-of-supported-languages-and-lexers).
+
+### Note Blocks
+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`.
+
+You'd write a block like this:
+```md
+> warning "I am a warning"
+> The body of the warning goes here. Premonition allows you to write any `Markdown` inside the block.
+```
+
+Notes *must* include a `[]` in the heading/title, even if it's empty.
+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)
+
+### Redirect to a workspace
+Occasionally, you'll want to deep-link into the Segment app to link a reader to a specific page or screen. Previously we'd throw them an URL and say "replace {MY SLUG} with your actual workspace slug", but now you can use the slug of `goto-my-workspace` and the Segment app will redirect them.
+https://app.segment.com/goto-my-workspace/destinations/catalog
+
+
+
+## Set up on Mac using the Env script
+
+We've written a bash script to set up the environment for you on a Mac computer. If you're on another platform, please [email us](mailto:docs-feedback@segment.com) or [file a Github Issue](https://github.com/segmentio/segment-docs/issues/new) to request other instructions, and we'll see what we can do.
+
+> info ""
+> You only need to run `make env` once!
+
+1. Set up your Github config so you have an SSH key on your laptop.
+2. Clone this repo locally.
+3. Open your Terminal app and navigate to where you cloned the docs repo.
+4. Start by checking what directory you’re in, to make sure you’re in the `segment-docs` repo.
+ Type `pwd` (which means “print working directory”) to check. You should see something like `~/repos/segment-docs`.
+5. Type `make env`.
+ The script first checks to see if you have Brew installed, and if you don’t, it installs it. It then runs more brew commands to download and install the software you need.
+
+ > **Heads up**! You’re going to need to enter your laptop password as part of this installation, but only once!
+
+ Once the installer completes, you still need to do a few small configuration tasks.
+
+6. Open the Atom app, then click the **Atom** menu in the top left, and click **Install Shell Commands**.
+7. Next, make sure you’re showing invisible characters. These are important for seeing weird formatting in the docs, and for troubleshooting markdown.
+ Go to **Preferences > Editor**, and scroll down to **Show Invisibles**. Make sure that’s checked!
+ 
+
+8. Finally, configure bash completion by adding tab-completion to your `.bash` profile:
+
+ 1. Open Terminal and type `atom ~/.bash_profile` to open the file in Atom.
+ 2. Paste the following anywhere in the file:
+ `[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"`
+ 3. Save and close the file in Atom.
+ 4. Quit and relaunch both Terminal and Atom.
+
+## Refresh the Segment catalog
+
+The Segment Docs pull a list of sources and destinations from the public ConfigAPI's Catalog API endpoint. We save these files locally (in YML files in `src/_data/catalog/`) so that you can run the docs locally without needing to touch the ConfigAPI, but these files can fall out of date.
+
+To update the files, you run `make catalog` from your Terminal. Before you can do that, follow the instructions below:
+
+### Set up to refresh the Segment catalog
+
+To use the `make catalog` command to update the list of sources and destinations that Segment supports, you'll need [a basic token for the Segment ConfigAPI](https://segment.com/docs/config-api/authentication/). You'll save this in a `.env` file on your computer, which will allow the script to talk to the Segment APIs.
+
+1. If you don't already have one, sign up for a free Segment workspace.
+2. Copy the `.env.example` file at the root of this directory, and rename it to remove the word "example". It should *just* be called `.env` when you're done. **Do NOT check in your .env file.**
+2. Go to the workspace's **Settings > Access Management > Tokens** tab (or click [here](https://app.segment.com/goto-my-workspace/settings/access-management)).
+3. Click **Create Token**.
+4. Add a description (you and specify that you're using it for docs purposes).
+5. Select **Workspace Member**, check **Source Admin**, and select one or all sources. You can grant this token more privileges, but that is unnecessary for this use.
+5. Click **Create**.
+6. Copy the token payload, and paste it after the equals sign (`=`) after "PLATFORM_API_TOKEN".
+7. Save and close the file. Before running the make command you may need to type `env` and enter into Terminal, or otherwise restart your Terminal session.
diff --git a/devguide.md b/devguide.md
new file mode 100644
index 0000000000..1fe4e9a208
--- /dev/null
+++ b/devguide.md
@@ -0,0 +1,124 @@
+# Segment Docs Dev guide
+
+Aka, where all the bodies are buried.
+
+
+### Quickstart (local development with docker)
+You will need to have Docker installed https://docs.docker.com/install/
+
+* If using Linux, run `docker-compose up`
+* Visit http://localhost:4000/docs/
+
+### Local development with `ruby` and `node`, without platform-api
+
+If using OSX:
+ * Install command line tools, `xcode-select --install`
+ * Install `Ruby` >= 2.3.0 https://www.ruby-lang.org/en/documentation/installation/
+ * Ensure you're running `RubyGems` >= 2.5.0 by running `gem update --system` followed by `gem --version`
+ * Install `Bundler 2` with `gem install bundler`
+ * Install `Node` https://nodejs.org/en/download/
+ * Install `Yarn` https://yarnpkg.com/en/docs/install
+ * Run server, `make dev`
+ * Visit http://localhost:4000/docs/
+
+
+
+ ## Developer information
+
+
+ ### Layouts
+ `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.
+
+ ### Platform Config API + Catalog
+
+ #### Data Source
+ 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.
+
+ 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.
+
+ #### API Key
+ 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`
+
+ 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
+
+ **NOTE: Never check-in `.env` or remove it from `.gitignore`.**
+
+ 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.
+
+ ##### Chamber
+
+ If you installed and have access to `chamber`, run the following command:
+
+ ```bash
+ $ aws-okta exec prod-privileged -- chamber read segment-docs platform_api_key
+ ```
+
+ or for staging...
+
+ ```bash
+ $ aws-okta exec stage-privileged -- chamber read segment-docs platform_api_key
+ ```
+
+ You should get something like this as the output of the command.
+ ```bash
+ Key Value Version LastModified User
+ platform_api_key [REDACTED FOR DOCS] 2 08-05 10:24:55 arn:aws:sts::752180062774:assumed-role/production-write/bryan.mikaelian@segment.com
+ ```
+
+ Edit the `.env` file (generated from `make env`) and replace the environment variable with the token above. `make catalog` should then work and you should see some output like this:
+
+ ```bash
+ $ make catalog
+ "Saving catalogs from Platform API..."
+ "Finished Destinations."
+ "Finished Sources."
+ "Done."
+ ```
+
+ ##### Bring your own token
+
+ You create your own token in the Segment App. You can use your own personal workspace, or if you have access to them, use [`segment-engineering`](https://app.segment.com/segment-engineering/settings/access-management) or [`segment_prod`](https://app.segment.com/segment_prod/settings/access-management). Go to **Settings > Access Management > Tokens**.
+ Any type of token will work, but you might want to limit it to a read-only token. Make sure you label it so folks know what it's for!
+
+ Once you make a new token, paste the token value in the `.env` file like so:
+
+ ```text
+ PLATFORM_API_TOKEN=(token value here)
+ ```
+ You can now run `make catalog`!
+
+
+ #### Catalog Data + Doc Links
+ By default, the links on the catalog page and respective sidenavs 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.
+
+ #### Object Sources and Warehouses
+ These two catalogs are hardcoded in the `_data` directory since the Config API does not expose these resources.
+
+ ### Sidenav
+ 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.
+
+ ### Breadcrumb
+ The current breadcrumb is currently determined based on the `page.path` and the current page's `title` front-matter attribute.
+
+ ### Searching
+ Swiftype is set up as a script in `_layouts/default.html`
+
+
+ ## Testing
+
+ ### Build Testing
+ Currently the only automatic testing we perform is linting on the configuration yaml files to ensure proper the project will build.
+
+ TODO: define rules for markdown linting and clean up linting errors
+ `npx remark ./src --use preset-lint-markdown-style-guide`
+
+ ### Manual Testing
+ There is as also some manual testing scripts that can be run to validate the build.
+
+ 1. `tests/redirects/redirects_bash`: used for validating a list of paths that we have nginx redirects for
+
+ 2. `tests/externalLinks/linkTester_bash`: used to validate that external links referenced in docs point to a validate endpoint
+
+ 3. `tests/imageSizes/getImageSizes.js`: used to get the 10 largest images in the repo.
+
+ 4. `npx mdspell 'src/**/*.md' -r --en-us`: used to validate spelling in docs, needs to be configured to add Segment terms.
diff --git a/guide-imgs/atom-fetch.png b/guide-imgs/atom-fetch.png
new file mode 100644
index 0000000000..2828db1767
Binary files /dev/null and b/guide-imgs/atom-fetch.png differ
diff --git a/guide-imgs/atom-github-new-pr.png b/guide-imgs/atom-github-new-pr.png
new file mode 100644
index 0000000000..344f4f031f
Binary files /dev/null and b/guide-imgs/atom-github-new-pr.png differ
diff --git a/guide-imgs/atom-github-pr-form.png b/guide-imgs/atom-github-pr-form.png
new file mode 100644
index 0000000000..0e238d6cd9
Binary files /dev/null and b/guide-imgs/atom-github-pr-form.png differ
diff --git a/guide-imgs/atom-github-reviewers.png b/guide-imgs/atom-github-reviewers.png
new file mode 100644
index 0000000000..2b4c0ddf5e
Binary files /dev/null and b/guide-imgs/atom-github-reviewers.png differ
diff --git a/guide-imgs/atom-new-branch.gif b/guide-imgs/atom-new-branch.gif
new file mode 100644
index 0000000000..dd60d64b62
Binary files /dev/null and b/guide-imgs/atom-new-branch.gif differ
diff --git a/guide-imgs/atom-stage-commit-publish.gif b/guide-imgs/atom-stage-commit-publish.gif
new file mode 100644
index 0000000000..0a1ac0aad6
Binary files /dev/null and b/guide-imgs/atom-stage-commit-publish.gif differ
diff --git a/guide-imgs/github-commit.png b/guide-imgs/github-commit.png
new file mode 100644
index 0000000000..9b25b4f95a
Binary files /dev/null and b/guide-imgs/github-commit.png differ
diff --git a/guide-imgs/github-edit-this-file.png b/guide-imgs/github-edit-this-file.png
new file mode 100644
index 0000000000..e53c493ce8
Binary files /dev/null and b/guide-imgs/github-edit-this-file.png differ
diff --git a/guide-imgs/segment-sloth-heart.png b/guide-imgs/segment-sloth-heart.png
new file mode 100644
index 0000000000..66ae562cdf
Binary files /dev/null and b/guide-imgs/segment-sloth-heart.png differ
diff --git a/guide-imgs/show-invisibles.png b/guide-imgs/show-invisibles.png
new file mode 100644
index 0000000000..7ce1f04ebe
Binary files /dev/null and b/guide-imgs/show-invisibles.png differ
diff --git a/scripts/atom.sh b/scripts/atom.sh
new file mode 100644
index 0000000000..86761f17e5
--- /dev/null
+++ b/scripts/atom.sh
@@ -0,0 +1,31 @@
+#!/bin/bash
+# script to set up atom on mac heavily relying on brew
+
+which -s brew
+if [[ $? != 0 ]] ; then
+ # Install Homebrew
+ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+else
+ echo " ✔ Brew already installed"
+ echo " Updating Brew"
+ brew update
+fi
+
+which -s atom
+if [[ $? != 0 ]] ; then
+ brew cask install atom
+ open -a Atom
+ which -s atom
+ if [[ $? != 0 ]] ; then
+ echo " Atom installed, but command shell not installed. Please click Atom > Install Shell Commands from in the Atom application."
+ else
+ # install atom packages which make markdown easy
+ echo "Installing useful Atom packages"
+ apm install language-markdown markdown-preview-plus minimap sort-selected-elements wordcount markdown-table-editor markdown-toc
+ fi
+else
+ echo " ✔ Atom already installed"
+ # install atom packages which make markdown easy
+ echo "Installing useful Atom packages"
+ apm install language-markdown markdown-preview-plus minimap sort-selected-elements wordcount markdown-table-editor markdown-toc
+fi
diff --git a/scripts/env.sh b/scripts/env.sh
index fb6c55ea3c..b941b80c0a 100644
--- a/scripts/env.sh
+++ b/scripts/env.sh
@@ -30,13 +30,22 @@ echo "[[ -r \"/usr/local/etc/profile.d/bash_completion.sh\" ]] && . \"/usr/local
which -s atom
if [[ $? != 0 ]] ; then
brew cask install atom
+ open -a Atom
+ which -s atom
+ if [[ $? != 0 ]] ; then
+ echo " Atom installed, but command shell not installed. Please click Atom > Install Shell Commands from in the Atom application."
+ else
+ # install atom packages which make markdown easy
+ echo "Installing useful Atom packages"
+ apm install language-markdown markdown-preview-plus minimap sort-selected-elements wordcount markdown-table-editor markdown-toc
+ fi
else
echo " ✔ Atom already installed"
+ # install atom packages which make markdown easy
+ echo "Installing useful Atom packages"
+ apm install language-markdown markdown-preview-plus minimap sort-selected-elements wordcount markdown-table-editor markdown-toc
fi
-# install atom packages which make markdown easy
-echo "Installing useful Atom packages"
-apm install language-markdown markdown-preview-plus minimap sort-selected-elements wordcount markdown-table-editor markdown-toc
# install stuff you need to run the docs locally
@@ -47,13 +56,6 @@ else
echo " ✔ Xcode command line tools already installed"
fi
-which -s ruby
-if [[ $? != 0 ]] ; then
- brew install ruby
-else
- echo " ✔ Ruby already installed"
-fi
-
which -s node
if [[ $? != 0 ]] ; then
brew install node
@@ -68,6 +70,16 @@ else
echo " ✔ Yarn already installed"
fi
+brew install ruby
+
+which -s bundler
+if [[ $? != 0 ]] ; then
+ gem install -n /usr/local/bin bundler:2.1.2
+ echo " ✔ Bundler installed"
+else
+ echo " ✔ Bundler already installed"
+fi
+
echo " Updating your Gem installation. Please enter your password to sudo."
sudo gem update --system -n /usr/local/bin
echo "Gem version " $(gem --version) "installed"
@@ -92,11 +104,3 @@ echo "Gem version " $(gem --version) "installed"
# " ✔ Gem version $version already installed"
# fi
# fi
-
-which -s bundler
-if [[ $? != 0 ]] ; then
- gem install bundler:2.1.2 --user-install
- echo " ✔ Bundler installed"
-else
- echo " ✔ Bundler already installed"
-fi
diff --git a/styleguide.md b/styleguide.md
new file mode 100644
index 0000000000..fc33411529
--- /dev/null
+++ b/styleguide.md
@@ -0,0 +1,113 @@
+# Style guide
+
+This doc is for keeping track of [style decisions](#style-decisions), [structure decisions](#doc-structure), and [formatting gotchas](#formatting) in the Segment Docs.
+
+## Style decisions
+
+## General text style
+
+- UI items are described by their text label in **Bold**. We don't add an explicit reference to what type of affordance it is (button, toggle, etc) unless needed for clarity. "Click **Send**." rather than "Click the **Send** button."
+- Use single-backtick `code format` for variables, for commands or values that need to be entered by the user, and the names of methods or calls when referring to them in context of an impementation (for example: "You'll make an identify call to capture this information" vs "In your code, edit the `identify` call...").
+- One-line or less of code can be formatted using single-backtick "code format". For more than one line of code, use a code block.
+- Code blocks must use the triple-backtick format, and must include a syntax highlighter cue (even if that cue is "text" or "none".)
+
+### When to capitalize
+
+Capitalize Segment (obviously ;) ) and Segment product names. For example, "privacy" by itself isn't capitalized, but "Segment Privacy Portal" is. Page titles Other UI text should be in lower case.
+
+Capitalize the words "Sources", "Destinations", and "Warehouses" when referring them as product names (for example: “You can use Sources to…”) but decap them when referring to them generically (“You can connect your warehouse to…”)
+
+### Connection modes
+Device-mode, Client Side, Cloud-mode, Server side
+
+We’ve had a lot of confusion in the past due to using device-mode and client-side, and cloud-mode and server-side interchangeably when referring to our Connection Modes. To reduce confusion, we’re standardizing.
+
+There are legitimate uses of both the terms client-side and server-side when referring to things _other than_ our connection modes, so we’re moving to use **Device-mode** and **Cloud-mode** instead. Laura made an initial scrub through to change all instances of “client-side” to “device mode”, but there are some legitimate uses of “server side” in the docs which prevent us doing a full find-and-replace to change those.
+
+Device-mode and Cloud-mode are always hyphenated. They should be capitalized when referring to the mode in abstract (as a product name), but can be decapped when used in running text about a specific destination.
+
+### Use this not that
+
+- Don't use characters like ampersand (`&`) -> Use the word "and".
+- Don't use "ie", write out "for example".
+- Don't use the word "via". Instead use the words "using", "with", or sometimes "through" as appropriate.
+- Setup is one word describing a noun ("your recording studio setup") which we should more properly call "configuration." "Set up" is an action, and requires a space.
+- "Login" is a noun, and we should use "credentials", "account", or similar. "Log in" is an action and requires a space.
+
+## Doc structure
+
+### Adding Images
+
+**All images should be saved locally! No linking to 3rd party-hosted images!**
+As CDN hosting is from the publish side, we shouldn't be worrying about that at the file level.
+
+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.
+
+There are no naming conventions at this time. Anything you see with `asset` was dowloaded by a script to save it from Contents.io. :)
+
+### Signposting
+
+The Segment-App section should contain roughly a page for each page within the web app. If there are in-depth docs about that feature elsewhere, the page should describe what it does at a high-level, and link out to those docs. This gives us a comprehensive UI reference for novice readers that serves as a signpost to the details they may or may not need, and prevents us pulling all of the docs into the Segment-app section.
+
+
+## Troubleshooting Formatting
+
+
+### Mixed markdown and HTML
+
+You can mix markdown and html in the same file, but you need to be careful to keep these items on separate lines. The one exception to this is
+
+### Code fences and syntax highligher cues
+
+When giving a code example that is more than a line long, use a code block. (For keyboard shortcuts, variables, and commands, use the single-backtick `code format`)
+
+Always use triple-backtick code fences to create a code block. Do not use the three-indent (three tabs/six spaces) mode, as this can conflict with nested list rendering.
+
+When you create a code fence, add a syntax highlighter cue after the first set of backticks - this tells the renderer how to color the text for better readability. We use Rouge, and you can read the [long list of the cues Rouge accepts](https://github.com/rouge-ruby/rouge/wiki/list-of-supported-languages-and-lexers) to find one that works for your code snippet.
+
+### Tables
+
+Tables can be a mix of markdown and HTML, but only they can't be both markdown and HTML on the same line.
+
+Markdown tables are built on a single line per table row, and so have to be pretty much 100% markdown. Markdown tables aren't fun, but you can install the Atom `markdown-table-editor` package which makes them easier to work with.
+
+Tables in HTML can include html formatting, OR markdown formatting, but not both in the same cell. We built a ruby hook that adds a `markdown=1` cue to all `` paragraph markers inside a table cell. + +## Troubleshooting Paper Exports + +Many of these docs were exported from Paper, which means that they'll have some quirks to sort out. + +### Endumben-ing +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... + +’ ‘ “ ” If you "change all" in Atom, you'll remove these examples so please revert changes to this file. ;) + +Note that these won't always render in Github, so you'll have to make this change using Atom or another text editor. + +If the examples get removed you can also type these on a Mac by typing +- Option + [ +- Option + Shift + [ +- Option + ] +- Option + Shift + ] + +### Headings vs Titles + +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 ) + +### Image captions + +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. + +```md + +``` + +If you want to preserve this as alt-text, awesome. However, if you want to use this as a "caption", you'll have to copy and paste that text below the image. You can put it in italic format if you'd like. + +### Code-block cleanup + +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. + +Instead, de-indent your code (shift-tab), and add a code-fence of three backticks at the top and bottom. + +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). See the [section on code fences](#code-fences-and-syntax-highligher-cues) above for more details.