Docs: (getstarted.md) Update instructions

doc/content/getstarted.md

@@ -2,62 +2,84 @@
 title: Get Started
 ---
 
-## The Scientific Python theme for Hugo
+The **Scientific Python Hugo Theme** is a theme for the [Hugo](https://gohugo.io) static site generator, inspired by the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/).
 
-The **Scientific Python Hugo Theme** is a theme for the
-[Hugo](https://gohugo.io) static site generator based on the
-[Fresh](https://github.com/StefMa/hugo-fresh) theme.
+To use this theme on your site, follow these instructions.
 
-To use the theme, you will need to
-[download hugo](https://github.com/gohugoio/hugo/releases)
-and place it on your path.
+## Install Hugo
 
-## Download and install
+To use this theme, you will need Hugo.  Hugo is a static site generator, i.e. it takes Markdown source files and transforms them into a website.
 
-1. Download [the theme ZIP file](https://github.com/scientific-python/scientific-python-hugo-theme/archive/refs/heads/main.zip) and extract it.
+1. Install Hugo according to [its installation instructions](https://gohugo.io/installation/).  The standard edition of Hugo is sufficient; you may install the extended edition, but it is not required by this theme.
 
-2. Copy the `doc` folder as a template of your new website:
+2. Verify that the `hugo` binary is present in your `PATH` environment variable by running the command `hugo version`, which should output a message like:
+
+   ```
+   hugo v0.120.3-a4892a07b41b7b3f1f143140ee4ec0a9a5cf3970 linux/amd64 BuildDate=2023-11-01T17:57:00Z VendorInfo=gohugoio
+   ```
+
+### Install Dart Sass
+
+This theme also uses the [Dart Sass](https://sass-lang.com/dart-sass) CSS transpiler.  To install it, follow [Hugo's Dart Sass installation guide](https://gohugo.io/hugo-pipes/transpile-sass-to-css/#dart-sass).
+
+## Install theme
+
+This theme is designed to be used as a Git submodule inside the repository that contains the Web site's source files, which Hugo builds from.
+
+1. Create a Git repository for your new site:
 
    ```sh
-   cp -r scientific-python-hugo-theme-main/doc ./my-website
-   cd my-website
+   mkdir NEW-SITE && cd NEW-SITE && git init
    ```
 
-3. Initialize git and add `scientific-python-hugo-theme` as a submodule:
+2. Add the theme repository as a submodule:
 
    ```sh
-   git init
    git submodule add https://github.com/scientific-python/scientific-python-hugo-theme themes/scientific-python-hugo-theme
    ```
 
-4. Build your site:
+3. Copy the theme's documentation site as a template for your site:
 
    ```sh
-   make serve
+   cp -a themes/scientific-python-hugo-theme/doc/* .
    ```
 
-Browse to `http://localhost:1313`, and hopefully you will see your new site!
+4. Test the site by running `make serve`.  The command's output should include a line like:
 
-## Build HTML
+   ```
+   Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
+   ```
 
-Run `make html`. Output appears in `./public`.
+   Load that URL in your browser, and you should see the theme's documentation page, which indicates that the site compiled successfully, and you can now customize it with your own content.
 
-## Customizing the site
+## Develop your site
 
-Edit `config.yaml` to your liking.
+Now you may proceed to develop your site by adding content and custom resources like CSS or JavaScript.
 
-To customize styling, add one or more `*.css` files to the `assets/css` directory.
-These files may make use of Hugo templating,
-e.g. to access configuration variables as `{{ .Site.Params.somevar }}`.
+As you work, a live preview of your site is available via `make serve`.
 
-Add custom JavaScript to `static/js/*.js`.
+### Customization
 
-## Next steps
+#### `config.yaml`
 
-See [features]({{< relref "features" >}}) and [shortcodes]({{< relref "shortcodes" >}}).
+The main configuration file is `config.yaml`, in the repository's root directory.  It is used to set the name of the site, configure navigation bars, etc.
+
+For examples of what's possible by editing this file, see these repositories which also use this theme: [scientific-python.org](https://github.com/scientific-python/scientific-python.org/blob/main/config.yaml), [numpy.org](https://github.com/numpy/numpy.org/blob/main/config.yaml.in), and [scipy.org](https://github.com/scientific-python/scientific-python.org/blob/main/config.yaml).
+
+#### CSS
+
+To customize styles, add CSS files to the `assets/css/` directory.  It's recommended to put your customizations in a `custom.css` file, but you may add additional ones as well.
+
+These files may use Hugo templates.  For example, configuration variables from the `config.yaml` file may be accessed like `{{ .Site.Params.VARIABLE }}`.
+
+#### JavaScript
+
+Add custom JavaScript files to the `static/js/` directory with a `.js` extension.  They will automatically be included in the built pages.
+
+## Build your site
+
+To build your site for deployment, run `make html`.  The generated files will be placed in the `public/` directory.
+
+## Next steps
 
-See the
-[scientific-python.org](https://github.com/scientific-python/scientific-python.org),
-[numpy.org](https://github.com/numpy/numpy.org), and
-[scipy.org](https://github.com/scipy/scipy.org) repositories for
-examples of what is possible by changing `config.yaml`.
+To learn about the features provided by this theme, see [features]({{< relref "features" >}}) and [shortcodes]({{< relref "shortcodes" >}}).