Skip to content

Commit

Permalink
Docs: (getstarted.md) Update instructions (#401)
Browse files Browse the repository at this point in the history 
* Docs: (getstarted.md) Update instructions

See <#397>.

* Change: Address feedback

Co-authored-by: Stefan van der Walt <stefanv@berkeley.edu>
Co-authored-by: Jarrod Millman <jarrod.millman@gmail.com>

* Add: Dart Sass installation instructions

Hugo's guide seems comprehensive and well-written, so we link to it.

* Minor change

Co-authored-by: Stefan van der Walt <stefanv@berkeley.edu>

* '[pre-commit.ci 🤖] Apply code format tools to PR'

---------

Co-authored-by: Stefan van der Walt <stefanv@berkeley.edu>
Co-authored-by: Jarrod Millman <jarrod.millman@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
  • Loading branch information
@alphapapa @stefanv
@jarrodmillman @pre-commit-ci
4 people committed Nov 9, 2023
1 parent abeb16c commit cba8f23
Showing 1 changed file with 54 additions and 32 deletions.
86 changes: 54 additions & 32 deletions doc/content/getstarted.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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" >}}).

0 comments on commit cba8f23

Please sign in to comment.