Getting Started

Overview

In surveydown, surveys are designed using markdown and R code in a single Quarto document (a .qmd file). There is no GUI or drag-and-drop interface - simply write plain text (markdown & R code) and boom - you have a survey! 🎉

The {surveydown} R package provides a set of functions for defining the survey content and configuration options. Each function starts with sd_ to make them easy to identify.

The platform is based on some basic principles:

  • Add content to your survey using markdown text (or in RStudio use the visual editor).
  • Define survey questions in R code chunks with the sd_question() function.
  • Define pages using fences (:::), with navigation buttons handled using the sd_next() function.
  • Add rich functionality to your survey using config options in the server code chunk.
  • Store your respondent data on Supabase by setting the database in the server code chunk.

This approach ensures a flexible survey platform that is fully reproducible and easy to customize.

The remaining steps on this page will guide you through the process of creating a surveydown survey.

1. Install

See the Installation page.

2. Start with a template

In the R console, run the following to to setup a template survey:

surveydown::sd_create_survey("path/to/folder")

This will create a folder located at "path/to/folder" with the following files:

  • example.qmd: a template survey you should edit.
  • example.Rproj: An RStudio project file (helpful if you’re working in RStudio)
  • _extensions: A folder with the surveydown Quarto extension needed to make everything work (don’t modify this).
Important

Every survey created with {surveydown} should be in its own separate project folder.

3. Add content

See the Survey Components page for details on the main components in a surveydown survey. For a quick overview, here’s how you add pages and questions:

  • Add pages with fences, like this:
::: {#page1 .sd-page}

Page 1 content here

:::
  • Add questions with the sd_question() function in code chunks (see the Question Types page for more on the types of questions supported). For example, here’s a multiple choice question:
```{r}
sd_question(
  type  = 'mc',
  id    = 'penguins',
  label = "Which is your favorite type of penguin?",
  option = c(
    'Adélie'    = 'adelie',
    'Chinstrap' = 'chinstrap',
    'Gentoo'    = 'gentoo'
  )
)
```

4. Add configuration options

In the server chunk (bottom of the .qmd file), add control logic and other configuration options to your survey with the sd_config() function. See the Configuration Options page for more details.

5. Setup your database

In the setup chunk (top of the .qmd file), setup your database with the sd_database() function. You can also leave it blank to preview / edit your survey without database connected, or set ignore = TRUE to run the survey without storing data. See the Store Data page for more details.

6. Locally preview

Preview your survey by clicking the “Run Document” button in RStudio or in your terminal running the command (replacing survey_file_name.qmd with the name of your survey .qmd file):

quarto serve survey_file_name.qmd

7. Deploy

Deploy your survey by hosting it on your favorite server, like shinyapps.io, huggingface, etc. See the Deployment page for more details.

Back to top