anchor.diff:  
   Create a pipeline from the Pipelines page of Buildkite using the ➕ button.
   
  -Required fields are 'name', 'repository', and 'steps'. You can leave the 'steps' with only the default empty command step to get started, the steps can be edited at any time from your pipeline settings page.
  +Required fields are 'name', 'repository'.
   
   <%= image "new-pipeline-setup.png", width: 1768/2, height: 1169/2, alt: "Screenshot of the 'New Pipeline' setup form" %>
   
   You can set up webhooks at this point, but this step is optional. These webhook setup instructions can be found in pipeline settings on your specific repository provider page.
   
  -You can also use the REST API to create a pipeline and define your steps. See the [Pipelines API](/docs/apis/rest-api/pipelines) for further information.
  +Both the REST API and GraphQL API can be used to create a pipeline programatically. See the [Pipelines REST API](/docs/apis/rest-api/pipelines) and the [GraphQL API](https://buildkite.com/docs/apis/graphql-api) for details and examples.
   
   ## Adding steps
   
  -There are two ways to add steps to your pipeline: with the visual editor in Buildkite or with a `pipeline.yml` file. You can add steps immediately during your initial pipeline setup, or you can edit them on the pipeline settings page.
  -
  -### Visual pipeline editor
  -
  -Add steps to your pipeline using the ➕ dropdown button. You can add [command](/docs/pipelines/command-step), [wait](/docs/pipelines/wait-step), and [block](/docs/pipelines/block-step) steps here.
  -
  -Command steps can be configured using the expandable sections on the right of the step settings.
  -
  -For more complex steps, like trigger steps, or those utilizing plugins or advanced configuration, you'll need to use a `pipeline.yml` file.
  +There are two ways to define steps in your pipeline: using the YAML step editor in Buildkite or with a `pipeline.yml` file. Pipeline steps can be edited from the Pipeline Settings page. 
  +
  +### YAML steps editor
  +
  +To add steps using the YAML editor, click the 'Edit Pipeline' button on the Pipeline Settings page.
  +
  +Starting your YAML with the `steps` object, you can add as many steps as you require of each different type. Quick reference documentation and examples for each step type can be found in the sidebar on the right. 
   
   ### Pipeline.yml file
   
  -Before getting started with a pipeline.yml file, you'll need to tell Buildkite where to find your steps.
  -
  -In your Buildkite pipeline settings, add a new step using the ➕ button and choose 'read steps from repository'.
  -
  -<%= image "pipeline-upload-step.png", width: 612/2, height: 484/2, alt: "Screenshot of the 'Read steps from repository' menu item" %>
  -
  -Your pipeline will now show a new step labeled :pipeline: that runs a `buildkite-agent pipeline upload` command:
  -
  -<%= image "pipeline-upload.png", width: 1174/2, height: 452/2, alt: "Screenshot of the pipeline upload step" %>
  -
  -When you run a build, this step will add any steps defined in the `pipeline.yml` file to your Buildkite pipeline.
  -
  -Create a file called `pipeline.yml` in a directory called `.buildkite` in your repository. This file will describe your pipeline steps in YAML, and will be versioned alongside your code.
  -
  -If you're using any tools that ignore hidden directories, you can store your `pipeline.yml` file either in the top level of your repository, or in a non-hidden directory called `buildkite`.
  +Before getting started with a `pipeline.yml` file, you'll need to tell Buildkite where it will be able to find your steps.
  +
  +In the YAML steps editor, add the following YAML:
  +
  +```yml
  +steps:
  +  - label: ":pipeline: Pipeline upload"
  +    command: buildkite-agent pipeline upload
  +```
  +
  +When you eventually run a build from this pipeline, this step will look for a directory called `.buildkite` containing a file named `pipeline.yml`. Any steps it finds inside that file will be uploaded to Buildkite and will appear during the build.
  +
  +Create your `pipeline.yml` file in a `.buildkite` directory in your repo.
  +
  +If you're using any tools that ignore hidden directories, you can store your `pipeline.yml` file either in the top level of your repository, or in a non-hidden directory called `buildkite`. The upload command will search these places if it doesn't find a `.buildkite` directory. 
   
   The following example YAML defines a pipeline with one command step that will echo 'Hello' into your build log:
   
  
positive.code:   echo "  - command: \"run_tests "${test_dir}"\""
  done
  ```
  
  To use this script, you'd save it to `.buildkite/pipeline.sh` inside your repository, ensure it is executable, and then update your pipeline upload step to use the new script:
  
  
negative.code: # Defining Your Pipeline Steps
  
  Pipeline steps are defined in YAML can be stored in Buildkite or in your repository using a `pipeline.yml` file.
  
  Defining your pipeline steps in a `pipeline.yml` file gives you access to more configuration options and environment variables than the web interface, and allows you to version, audit and review your build pipelines alongside your source code.
  
  {:toc}
  
  