Project specify port for localhost

[javajon]

Bug description

When I render a Quarto qmd file "--to clean-revealjs" or "--to html" in VSCode via the preview button or CTRL-SHIFT-K Quarto uses a random port for the localhost. The Quarto Project Options and the Quarto Creating a Website states one can insert:

project:    
  preview: 
    port: 4200

However, despite having inserted this option into the project's _quarto.yml a random port number is still used. Other options in the _quarto.yml file are being applied, so I know the manifest is found and read. Some others have reported the same experience:

https://stackoverflow.com/questions/75715950/quarto-project-specify-port-for-localhost

Also tried setting the browser option to true and false which also had no effect.

project:    
  preview: 
    port: 4200
    browser: true

When the preview is re-rendered automatically after a change, then having a different port number is disruptive to the development workflow experience when showing the preview in both the VSCode preview and a browser.

Steps to reproduce

1. Add to the project directory a _quarto.yml file that contains:

project:    
  preview: 
    port: 4200

2. Open a .qmd file in VSCode with the Quarto extension.

3. Preview the .qmd document with CTRL-SHIFT-P | Quarto Preview Format... | format: clean-revealjs or format: html

Observe the quarto command in the terminal is missing the --port option.

No matter the port number specified, Quarto continues to choose a random port number instead of accepting the project.preview.port value in _quarto.yml.

Expected behavior

Terminal output for the preview command should say:

quarto preview [...qmd file...] --no-browser --no-watch-inputs --port 4200

Actual behavior

Terminal output for the preview command is missing the --port option, despite it being in the _quarto.yml file.

quarto preview [...qmd file...] --no-browser --no-watch-inputs

For this image, this was the command (at the top of the terminal scroll not seen in image below):

quarto preview c:/dev/trinity-courses/110-essentials-of-computing-S24/lectures/lecture-7.1.qmd --to clean-revealjs --no-browser --no-watch-inputs

Your environment

• IDE: VSCode 1.87
• Quarto plugin: v1.111.0
• Windows: 11

Quarto check output

Quarto 1.4.550
[>] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.11: OK
      Dart Sass version 1.69.5: OK
      Deno version 1.37.2: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
      Version: 1.4.550
      Path: C:\Users\jonat\AppData\Local\Programs\Quarto\bin
      CodePage: 1252

[>] Checking tools....................OK
      TinyTeX: v2023.10
      Chromium: 869685

[>] Checking LaTeX....................OK
      Using: TinyTex
      Path: C:\Users\jonat\AppData\Roaming\TinyTeX\bin\windows\
      Version: 2023

[>] Checking basic markdown render....OK

[>] Checking Python 3 installation....OK
      Version: 3.12.2
      Path: C:/Users/jonat/AppData/Local/Programs/Python/Python312/python.exe
      Jupyter: 5.7.1
      Kernels: python3

[>] Checking Jupyter engine render....OK

[>] Checking R installation...........OK
      Version: 4.2.3
      Path: C:/PROGRA~1/R/R-42~1.3
      LibPaths:
        - C:/Program Files/R/R-4.2.3/library
      knitr: 1.42
      rmarkdown: 2.21

[>] Checking Knitr engine render......OK

[mcanouil]

What's the exact setup you are using? I cannot reproduce in Book or Website projects

Website	Book

Side note about accessibility: please don't use "here" for links. That's uninformative for screen readers and readers.

Could you share a small self-contained "working" (reproducible) example to work with, i.e., a complete Quarto document or a Git repository? Thanks.

---

You can share a self-contained "working" (reproducible) Quarto document using the following syntax, i.e., using more backticks than you have in your document (usually four ````). See https://quarto.org/bug-reports.html#small-is-beautiful-aim-for-a-single-document-with-10-lines.

If you have multiple files (and if it is absolutely required to have multiple files), please share as a Git repository.

R	Python
`````md ````qmd --- title: "Reproducible Quarto Document" format: html engine: knitr --- This is a reproducible Quarto document. ```{r} x <- c(1, 2, 3, 4, 5) y <- c(1, 4, 9, 16, 25) plot(x, y) ```  The end. ```` `````	`````md ````qmd --- title: "Reproducible Quarto Document" format: html engine: jupyter --- This is a reproducible Quarto document. ```{python} import matplotlib.pyplot as plt x = [1, 2, 3, 4, 5] y = [1, 4, 9, 16, 25] plt.plot(x, y) plt.show() ```  The end. ```` `````

Additionally and if not already given, please share the output of quarto check within a code blocks (i.e., using three backticks ```txt), see https://quarto.org/bug-reports.html#check.

[javajon]

Here is a reproducible and minimal example:

The port problem happens when rendered to revealjs:

The same port problem happens when rendered to html:

Both files shown below are the only two files in the same directory.

project:
  preview:
    port: 4200

author: Chief Bromden

format:
  revealjs:
    date-format: long

  html:
    css: styles.css

---
title: Freedom
date: March 28, 2024
---

If you don't know where you are going, you'll end up someplace else.

Terminal output when render format is revealjs showing random port number, not the expected 4200:

$ quarto preview c:/dev/trinity-courses/110-essentials-of-computing-S24/quarto-8965-bug/bug-8965.qmd --to revealjs --no-browser --no-watch-inputs
pandoc 
  to: revealjs
  output-file: bug-8965.html
  standalone: true
  wrap: none
  default-image-extension: png
  html-math-method:
    method: mathjax
    url: >-
      https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS_HTML-full
  slide-level: 2

metadata
  link-citations: true
  width: 1050
  height: 700
  margin: 0.1
  center: false
  navigationMode: linear
  controlsLayout: edges
  controlsTutorial: false
  hash: true
  history: true
  hashOneBasedIndex: false
  fragmentInURL: false
  transition: none
  backgroundTransition: none
  pdfSeparateFragments: false
  lang: en
  auto-stretch: true
  author: Chief Bromden
  date-format: long
  title: Freedom
  date: 'March 28, 2024'

Output created: bug-8965.html

Watching files for changes
Browse at http://localhost:5971/bug-8965.html

[mcanouil]

So you are in a "default" project. Since the "default" was not really a project (as standalone documents). I believe this option never worked in such cases. With recent changes in the codebase, I assume now it should be possible to make this work.

[cscheid]

It should still have worked on a default project, though.

[392781]

I am running into the same problem... It would be good to be able to specify port-forwarding ahead of time (similar to how JupyterLab handles it): https://github.com/quarto-dev/quarto/issues/439

[bjornasm]

So you are in a "default" project. Since the "default" was not really a project (as standalone documents). I believe this option never worked in such cases. With recent changes in the codebase, I assume now it should be possible to make this work.

Does this mean that if OP specificies project to be website/manuscript/book/confluence it should work? F.ex

project:
  type: website
  preview:
    port: 4200

author: Chief Bromden

format:
  revealjs:
    date-format: long

  html:
    css: styles.css

[cderv]

Does this mean that if OP specificies project to be website/manuscript/book/confluence it should work?

Yes this is among the possibly options for configuring website: https://quarto.org/docs/reference/projects/websites.html#preview

[bjornasm]

@cderv - thank you four your answer. I did some testing, seems like it works if you specify it in _quarto.yml:

project:
  type: website
  output-dir: _output
  preview:
    port: 1234
    browser: false

This correctly starts a preview at port 1234.

However if you have it directly in the header of your index.qmd (or whatever) it won't:

(remember to remove from _quarto.yml)

---
title: "testQuarto"
project:
  type: website
  output-dir: _output
  preview:
    port: 4567
    browser: false
---

This is a Quarto website.

To learn more about Quarto websites visit <https://quarto.org/docs/websites>.

This starts a preview at port 3146.

This might be intended, I just wanted to share if anyone struggles with the same - put the preview settings in _quarto.yml not in the header of your document.

[cderv]

Yes this documented as a project option : https://quarto.org/docs/reference/projects/options.html#preview so should work when in a project.

[mcanouil]

Yes this documented as a project option : https://quarto.org/docs/reference/projects/options.html#preview so should work when in a project.

To be more accurate: it's a project level option and project level options live in _quarto.yml not in a document YAML frontmatter.

[cderv]

Thanks for the precision. Yes I assumed this was known, but better be thorough !

Any project key level option are for _quarto.yml. We should probably add mention of this in the reference page: https://quarto.org/docs/reference/projects/options.html 🤔