README.md

Live Server for Julia

This is a simple and lightweight development web-server written in Julia, based on HTTP.jl. It has live-reload capability, i.e. when modifying a file, every browser (tab) currently displaying the corresponding page is automatically refreshed.

LiveServer is inspired from Python's http.server and Node's browsersync.

Installation

To install it in Julia ≥ 1.6, use the package manager with

pkg> add LiveServer

Legacy notes

For Julia < 1.6, you can use LiveServer's version 0.9.2:

pkg> add LiveServer@0.9.2

For Julia [1.0, 1.3), you can use LiveServer's version 0.7.4:

pkg> add LiveServer@0.7.4

Make it a shell command

LiveServer is a small package and fast to load with one main functionality (serve), it can be convenient to make it a shell command: (I'm using the name lss here but you could use something else):

alias lss='julia -e "import LiveServer as LS; LS.serve(launch_browser=true)"'

you can then use lss in any directory to show a directory listing in your browser, and if the directory has an index.html then that will be rendered in your browser.

Usage

The main function LiveServer exports is serve which starts listening to the current folder and makes its content available to a browser. The following code creates an example directory and serves it:

julia> using LiveServer
julia> LiveServer.example() # creates an "example/" folder with some files
julia> cd("example")
julia> serve() # starts the local server & the file watching
✓ LiveServer listening on http://localhost:8000/ ...
  (use CTRL+C to shut down)

Open a Browser and go to http://localhost:8000/ to see the content being rendered; try modifying files (e.g. index.html) and watch the changes being rendered immediately in the browser.

In the REPL:

julia> using LiveServer
julia> serve(host="0.0.0.0", port=8001, dir=".") # starts the remote server & the file watching
✓ LiveServer listening on http://0.0.0.0:8001...
  (use CTRL+C to shut down)

In the terminal:

julia -e 'using LiveServer; serve(host="0.0.0.0", port=8001, dir=".")'

Open a browser and go to https://localhost:8001/ to see the rendered content of index.html or, if it doesn't exist, the content of the directory. You can set the port to a custom number. This is similar to the http.server in Python.

Serve docs

servedocs is a convenience function that runs Documenter along with LiveServer to watch your doc files for any changes and render them in your browser when modifications are detected.

Assuming you are in directory/to/YourPackage.jl, that you have a docs/ folder as prescribed by Documenter.jl and LiveServer installed in your global environment, you can run:

$ julia

pkg> activate docs

julia> using LiveServer

julia> servedocs()
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: ExpandTemplates: expanding markdown templates.
...
└ Deploying: ✘
✓ LiveServer listening on http://localhost:8000/ ...
  (use CTRL+C to shut down)

Open a browser and go to http://localhost:8000/ to see your docs being rendered; try modifying files (e.g. docs/index.md) and watch the changes being rendered in the browser.

To run the server with one line of code, run:

$ julia --project=docs -ie 'using LiveServer; servedocs()'

Serve docs with Literate.jl

When using the servedocs function together with documentation that contains Literate files, causing an $\infty$ loop is possible if servedocs is watching the generated *.md files for updates. To avoid an $\infty$ loop, use the literate keyword to indicate the location of the *.jl files. Then, any *.jl file is assumed to generate a corresponding *.md file, which will not be watched.

All files in src

docs
└── src
    ├── example.jl <-- Literate file
    ├── example.md <-- generated by Literate
    └── index.md

servedocs(literate="")

Literate files in a separate directory

docs
├── literate
│   └── example.jl <-- Literate file
└── src
    ├── example.md <-- generated by Literate
    └── index.md

servedocs(literate=joinpath("docs","literate"))

DEV/Path testing

See also issue #135 and related PRs.

• servedocs(), navigate to literate, images should show
• serve() navigate manually to docs/build/ should show, remove trailing slash in URL docs/build should redirect to docs/build/
• serve(dir=...) should work + when navigating to assets etc