diff --git a/NEWS.md b/NEWS.md
index 3d9740ba0..222fbfc8b 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,6 +1,7 @@
 # devtools (development version)
 
 * `build_manual()` reports more details on failure (#2586).
+* `build_vignettes()` and `clean_vignettes()` are now deprecated. We no longer recommend building and checking in vignettes; instead use `pkgdown::build_article()` to render articles locally for polishing (#2488).
 * New `check_mac_devel()` function to check a package using the macOS builder at https://mac.r-project.org/macbuilder/submit.html (@nfrerebeau, #2507)
 * `is_loading()` is now re-exported from pkgload (#2556).
 * `load_all()` now errors if called recursively, i.e. if you accidentally include a `load_all()` call in one of your R source files (#2617).
diff --git a/R/vignettes.R b/R/vignettes.R
index ec878eabb..327bc02ca 100644
--- a/R/vignettes.R
+++ b/R/vignettes.R
@@ -1,14 +1,11 @@
-#' Build package vignettes.
+#' Build package vignettes
 #'
-#' Builds package vignettes using the same algorithm that `R CMD build`
-#' does. This means including non-Sweave vignettes, using makefiles (if
-#' present), and copying over extra files. The files are copied in the 'doc'
-#' directory and an vignette index is created in 'Meta/vignette.rds', as they
-#' would be in a built package. 'doc' and 'Meta' are added to
-#' `.Rbuildignore`, so will not be included in the built package. These
-#' files can be checked into version control, so they can be viewed with
-#' `browseVignettes()` and `vignette()` if the package has been
-#' loaded with `load_all()` without needing to re-build them locally.
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' `build_vignettes()` is deprecated because we no longer recommend that you
+#' build and check in vignettes. Instead, use `pkgdown::build_article()` to
+#' render articles locally for preview and polishing.
 #'
 #' @template devtools
 #' @param quiet If `TRUE`, suppresses most output. Set to `FALSE`
@@ -22,11 +19,8 @@
 #' @inheritParams tools::buildVignettes
 #' @inheritParams remotes::install_deps
 #' @importFrom stats update
-#' @keywords programming
-#' @seealso [clean_vignettes()] to remove the pdfs in
-#'   \file{doc} created from vignettes
+#' @keywords internal
 #' @export
-#' @seealso [clean_vignettes()] to remove build tex/pdf files.
 build_vignettes <- function(
   pkg = ".",
   dependencies = "VignetteBuilder",
@@ -36,12 +30,13 @@ build_vignettes <- function(
   install = TRUE,
   keep_md = TRUE
 ) {
+  lifecycle::deprecate_warn("2.5.0", "build_vignettes()")
   pkg <- as.package(pkg)
   save_all()
 
   vigns <- tools::pkgVignettes(dir = pkg$path)
   if (length(vigns$docs) == 0) {
-    return()
+    return(invisible())
   }
 
   deps <- remotes::dev_package_deps(pkg$path, dependencies)
@@ -86,18 +81,22 @@ create_vignette_index <- function(pkg, vigns) {
   saveRDS(vignette_index, vignette_index_path, version = 2L)
 }
 
-#' Clean built vignettes.
+#' Clean built vignettes
+#'
+#' @description
+#' `r lifecycle::badge("deprecated")`
 #'
-#' This uses a fairly rudimentary algorithm where any files in \file{doc}
-#' with a name that exists in \file{vignettes} are removed.
+#' `clean_vignettes()` is deprecated because [build_vignettes()] is deprecated.
 #'
 #' @template devtools
+#' @keywords internal
 #' @export
 clean_vignettes <- function(pkg = ".") {
+  lifecycle::deprecate_warn("2.5.0", "clean_vignettes()")
   pkg <- as.package(pkg)
   vigns <- tools::pkgVignettes(dir = pkg$path)
-  if (path_file(vigns$dir) != "vignettes") {
-    return()
+  if (length(vigns$docs) == 0 || path_file(vigns$dir) != "vignettes") {
+    return(invisible())
   }
 
   cli::cli_inform(c(
diff --git a/_pkgdown.yml b/_pkgdown.yml
index 2cb2f760c..5ec45ef35 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -19,7 +19,9 @@ reference:
   desc: Primary commands used when developing a package.
   contents:
   - build
-  - starts_with("build_")
+  - build_manual
+  - build_rmd
+  - build_site
   - starts_with("check_")
   - check
   - create
@@ -36,7 +38,6 @@ reference:
 - title: Utilities
   contents:
   - bash
-  - clean_vignettes
   - dev_sitrep
   - github_pull
   - lint
@@ -48,6 +49,10 @@ reference:
   - update_packages
   - wd
   - save_all
+- title: Deprecated
+  contents:
+  - build_vignettes
+  - clean_vignettes
 
 news:
   releases:
diff --git a/man/build_vignettes.Rd b/man/build_vignettes.Rd
index f71509d9d..f0a9a6897 100644
--- a/man/build_vignettes.Rd
+++ b/man/build_vignettes.Rd
@@ -2,7 +2,7 @@
 % Please edit documentation in R/vignettes.R
 \name{build_vignettes}
 \alias{build_vignettes}
-\title{Build package vignettes.}
+\title{Build package vignettes}
 \usage{
 build_vignettes(
   pkg = ".",
@@ -58,20 +58,11 @@ outputs. See
 \url{https://bookdown.org/yihui/rmarkdown/html-document.html#keeping-markdown}.}
 }
 \description{
-Builds package vignettes using the same algorithm that \verb{R CMD build}
-does. This means including non-Sweave vignettes, using makefiles (if
-present), and copying over extra files. The files are copied in the 'doc'
-directory and an vignette index is created in 'Meta/vignette.rds', as they
-would be in a built package. 'doc' and 'Meta' are added to
-\code{.Rbuildignore}, so will not be included in the built package. These
-files can be checked into version control, so they can be viewed with
-\code{browseVignettes()} and \code{vignette()} if the package has been
-loaded with \code{load_all()} without needing to re-build them locally.
-}
-\seealso{
-\code{\link[=clean_vignettes]{clean_vignettes()}} to remove the pdfs in
-\file{doc} created from vignettes
+\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
 
-\code{\link[=clean_vignettes]{clean_vignettes()}} to remove build tex/pdf files.
+\code{build_vignettes()} is deprecated because we no longer recommend that you
+build and check in vignettes. Instead, use \code{pkgdown::build_article()} to
+render articles locally for polishing and rely on GitHub Actions or similar
+to build your pkgdown site.
 }
-\keyword{programming}
+\keyword{internal}
diff --git a/man/clean_vignettes.Rd b/man/clean_vignettes.Rd
index 4027137b2..6799d0fbe 100644
--- a/man/clean_vignettes.Rd
+++ b/man/clean_vignettes.Rd
@@ -2,7 +2,7 @@
 % Please edit documentation in R/vignettes.R
 \name{clean_vignettes}
 \alias{clean_vignettes}
-\title{Clean built vignettes.}
+\title{Clean built vignettes}
 \usage{
 clean_vignettes(pkg = ".")
 }
@@ -11,6 +11,8 @@ clean_vignettes(pkg = ".")
 package object.  See \code{\link[=as.package]{as.package()}} for more information.}
 }
 \description{
-This uses a fairly rudimentary algorithm where any files in \file{doc}
-with a name that exists in \file{vignettes} are removed.
+\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
+
+\code{clean_vignettes()} is deprecated because \code{\link[=build_vignettes]{build_vignettes()}} is deprecated.
 }
+\keyword{internal}
diff --git a/tests/testthat/_snaps/vignettes.md b/tests/testthat/_snaps/vignettes.md
new file mode 100644
index 000000000..8435fa064
--- /dev/null
+++ b/tests/testthat/_snaps/vignettes.md
@@ -0,0 +1,13 @@
+# build_vignettes() and clean_vignettes() are deprecated
+
+    Code
+      build_vignettes(pkg)
+    Condition
+      Warning:
+      `build_vignettes()` was deprecated in devtools 2.5.0.
+    Code
+      clean_vignettes(pkg)
+    Condition
+      Warning:
+      `clean_vignettes()` was deprecated in devtools 2.5.0.
+
diff --git a/tests/testthat/test-vignettes.R b/tests/testthat/test-vignettes.R
index f84625c3e..ab03a302b 100644
--- a/tests/testthat/test-vignettes.R
+++ b/tests/testthat/test-vignettes.R
@@ -1,4 +1,5 @@
 test_that("Sweave vignettes copied into doc", {
+  withr::local_options(lifecycle_verbosity = "quiet")
   if (!pkgbuild::has_latex()) {
     skip("pdflatex not available")
   }
@@ -13,6 +14,7 @@ test_that("Sweave vignettes copied into doc", {
 })
 
 test_that("Built files are updated", {
+  withr::local_options(lifecycle_verbosity = "quiet")
   # This test is time dependant and sometimes fails on CRAN because the systems are under heavy load.
   skip_on_cran()
   pkg <- local_package_copy(test_path("testMarkdownVignettes"))
@@ -29,6 +31,7 @@ test_that("Built files are updated", {
 })
 
 test_that("Rmarkdown vignettes copied into doc", {
+  withr::local_options(lifecycle_verbosity = "quiet")
   pkg <- local_package_copy(test_path("testMarkdownVignettes"))
   doc <- path(pkg, "doc")
 
@@ -37,6 +40,7 @@ test_that("Rmarkdown vignettes copied into doc", {
 })
 
 test_that("extra files copied and removed", {
+  withr::local_options(lifecycle_verbosity = "quiet")
   pkg <- local_package_copy(test_path("testMarkdownVignettes"))
   writeLines("a <- 1", path(pkg, "vignettes", "a.R"))
 
@@ -51,9 +55,18 @@ test_that("extra files copied and removed", {
 })
 
 test_that(".gitignore updated when building vignettes", {
+  withr::local_options(lifecycle_verbosity = "quiet")
   pkg <- local_package_copy(test_path("testMarkdownVignettes"))
   gitignore <- path(pkg, ".gitignore")
 
   suppressMessages(build_vignettes(pkg, quiet = TRUE))
   expect_true(all(c("/Meta/", "/doc/") %in% readLines(gitignore)))
 })
+
+test_that("build_vignettes() and clean_vignettes() are deprecated", {
+  pkg <- local_package_create()
+  expect_snapshot({
+    build_vignettes(pkg)
+    clean_vignettes(pkg)
+  })
+})