Skip to content

Commit

Permalink
Docs: (getstarted.md) Update instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
alphapapa committed Nov 8, 2023
1 parent 6ab8fab commit 31b36ba
Showing 1 changed file with 51 additions and 31 deletions.
82 changes: 51 additions & 31 deletions doc/content/getstarted.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,62 +2,82 @@
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 based on the
[Fresh](https://github.com/StefMa/hugo-fresh) theme.
[PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/).

To use this theme on your site, follow these instructions.

## Install Hugo

To use the theme, you will need to
[download hugo](https://github.com/gohugoio/hugo/releases)
and place it on your path.
Hugo is the program that reads the site's source files and generates the HTML and other files that are served to visitors in their Web browsers.

## Download and install
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.

1. Download [the theme ZIP file](https://github.com/scientific-python/scientific-python-hugo-theme/archive/refs/heads/main.zip) and extract it.
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
```

2. Copy the `doc` folder as a template of your new website:
## 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. Enter the directory of your site's Git repository. Or if your site doesn't yet have a Git repository, initialize one in a new directory, e.g. by running the command:

```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 Web browser and you should see the the theme's documentation page, indicating that installation is successful.

## Customizing the site
## Develop your site

Edit `config.yaml` to your liking.
Now you may proceed to develop your site, adding content, custom resources like CSS and images, etc.

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, you may see a preview of your site at any time by using the same `make serve` command and viewing it in your browser.

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.

## Build your site

To build your site for deployment, run the command `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 31b36ba

Please sign in to comment.